@elia97/officina 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elia Zarantonello
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# officina
+
+Gli strumenti dei progetti nati dai template del sistema (`vetrina`, poi `ecommerce` e `monorepo`), in un pacchetto solo: `@elia97/officina`. Ogni progetto li installa invece di portarne una copia, che alla prima modifica divergerebbe.
+
+Il metodo dice come si lavora e sta nel plugin `metodo`; l'officina è dove stanno gli strumenti che CI, lefthook e Vercel eseguono.
+
+## Uso in un progetto
+
+```sh
+pnpm add -D @elia97/officina
+```
+
+```json
+{
+  "scripts": {
+    "check:comments": "officina check comments --strict",
+    "check:language": "officina check language",
+    "check:routes": "officina check routes",
+    "check:roadmap": "officina check roadmap",
+    "check:placeholders": "officina check placeholders",
+    "check:vercel-cli": "officina check vercel-cli"
+  }
+}
+```
+
+I gate leggono dalla cartella corrente, che deve essere la radice del repository. Opzioni comuni: `--diff`, `--base <ref>`, `--head <ref>`, `--strict`, `--format text|github`.
+
+## Sviluppo
+
+```sh
+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
+```
+
+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
+```
+
+## Cosa arriverà
+
+I generatori (`officina gen …`) con i loro template, poi bundle budget, smoke di produzione, lighthouse, verifica analytics e icone.

package/dist/bin.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import process from 'node:process';
+// Un modulo per gate, caricato solo quando serve: `officina check routes` non paga il costo
+// degli altri cinque.
+const CHECKS = {
+    comments: () => import('./checks/comments.js'),
+    language: () => import('./checks/language.js'),
+    placeholders: () => import('./checks/placeholders.js'),
+    roadmap: () => import('./checks/roadmap.js'),
+    routes: () => import('./checks/routes.js'),
+    'vercel-cli': () => import('./checks/vercel-cli.js'),
+};
+const USAGE = `Uso: officina check <gate> [opzioni]\n\nGate: ${Object.keys(CHECKS).join(', ')}\nOpzioni comuni: --diff, --base <ref>, --head <ref>, --strict, --format text|github\n`;
+export async function run(argv) {
+    const [group, name, ...rest] = argv;
+    const load = group === 'check' && name !== undefined ? CHECKS[name] : undefined;
+    if (!load) {
+        console.error(USAGE);
+        return 2;
+    }
+    const { main } = await load();
+    return main(rest);
+}
+if (import.meta.main)
+    process.exit(await run(process.argv.slice(2)));

package/dist/checks/comments.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import { isNoisy, report, SCANNED } from '../lib/check-comments.js';
+import { cliOptions, exitCode, printFindings, readLines, scopedPaths } from '../lib/cli.js';
+// Esporta main ed esegue solo se lanciato direttamente: la coverage non segue i sottoprocessi,
+// quindi un gate provato con `node scripts/...` risulterebbe non testato.
+export function main(args) {
+    const options = cliOptions(args);
+    const paths = scopedPaths(options, (path) => SCANNED.test(path));
+    let totalLines = 0;
+    let totalComments = 0;
+    const findings = [];
+    for (const path of paths) {
+        const result = report(path, readLines(readFileSync(path, 'utf8')));
+        totalLines += result.total;
+        totalComments += result.comments;
+        findings.push(...result.findings.map((f) => ({
+            path,
+            line: f.line,
+            message: f.message,
+            severity: 'error',
+        })));
+        if (isNoisy(result))
+            findings.push({
+                path,
+                message: `${result.comments}/${result.total} righe sono commento`,
+                severity: 'warning',
+            });
+    }
+    const ratio = totalLines === 0 ? '0.0' : ((totalComments / totalLines) * 100).toFixed(1);
+    const scope = options.diff ? ' (solo file toccati dal branch)' : '';
+    console.log(`\ncheck:comments — ${totalComments}/${totalLines} righe sono commento (${ratio}%)${scope}\n`);
+    printFindings(findings, options.format);
+    if (findings.length === 0) {
+        console.log('  Niente sopra la soglia.\n');
+    }
+    else {
+        console.log('\n  Il default è non commentare: solo i casi particolari, al presente, sul codice\n' +
+            "  com'è adesso. Casi e forma in metodo.md, nel plugin metodo.\n");
+    }
+    return exitCode(findings, options.strict);
+}
+if (import.meta.main)
+    process.exit(main());

package/dist/checks/language.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import { findingsFor, isScanned } from '../lib/check-language.js';
+import { cliOptions, exitCode, printFindings, scopedPaths } from '../lib/cli.js';
+// Esporta main ed esegue solo se lanciato direttamente: la coverage non segue i sottoprocessi,
+// quindi un gate provato con `node scripts/...` risulterebbe non testato.
+export function main(args) {
+    const options = cliOptions(args);
+    const paths = scopedPaths(options, isScanned);
+    const findings = [];
+    for (const path of paths) {
+        for (const f of findingsFor(path, readFileSync(path, 'utf8')))
+            findings.push({
+                path,
+                line: f.line,
+                message: f.message,
+                severity: 'error',
+            });
+    }
+    const scope = options.diff ? ' (solo file toccati dal branch)' : '';
+    console.log(`\ncheck:language — ${paths.length} file con prosa${scope}\n`);
+    printFindings(findings, options.format);
+    if (findings.length === 0) {
+        console.log('  Tutto in italiano.\n');
+    }
+    else {
+        console.log('\n  Codice e identificatori in inglese, commenti e documentazione in italiano.');
+        console.log('  Le fonti del cliente sotto docs/sources/ non vengono guardate.\n');
+    }
+    return exitCode(findings, options.strict);
+}
+if (import.meta.main)
+    process.exit(main());

package/dist/checks/placeholders.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import process from 'node:process';
+import { parseArgs } from 'node:util';
+import { envFindings, placeholderSources, sourceFindings } from '../lib/check-placeholders.js';
+import { cliOptions, exitCode, printFindings } from '../lib/cli.js';
+function sourceScan(paths) {
+    return paths.flatMap((path) => sourceFindings(readFileSync(path, 'utf8')).map((hit) => ({ path, ...hit, severity: 'error' })));
+}
+function envScan(path) {
+    if (!existsSync(path))
+        return [{ path, message: "file dell'ambiente assente: lo scrive vercel pull", severity: 'error' }];
+    return envFindings(readFileSync(path, 'utf8')).map((hit) => ({ path, ...hit, severity: 'error' }));
+}
+function scan(env) {
+    if (env !== undefined) {
+        return {
+            scope: `ambiente in ${env}`,
+            findings: envScan(env),
+            fix: 'docs/guides/deploy-ops.md § Checklist per il go-live',
+        };
+    }
+    const paths = placeholderSources();
+    return { scope: `${paths.length} sorgenti`, findings: sourceScan(paths), fix: 'README.md § Cosa tocca il rebranding' };
+}
+export function main(args = process.argv.slice(2)) {
+    const { env } = parseArgs({ args, options: { env: { type: 'string' } } }).values;
+    const { scope, findings, fix } = scan(env);
+    console.log(`\ncheck:placeholders — ${scope}\n`);
+    printFindings(findings, cliOptions([]).format);
+    if (findings.length === 0) {
+        console.log('  Nessun segnaposto del template.\n');
+    }
+    else {
+        console.log(`\n  Da sostituire prima del deploy: ${fix}.\n`);
+    }
+    return exitCode(findings, false);
+}
+if (import.meta.main)
+    process.exit(main());

package/dist/checks/roadmap.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+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';
+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) {
+    const options = cliOptions(args);
+    // Un progetto appena creato dal template può non averla ancora scritta.
+    if (!existsSync(ROADMAP)) {
+        console.log(`\ncheck:roadmap — ${ROADMAP} non c'è ancora\n`);
+        return 0;
+    }
+    const findings = findingsFor(readFileSync(ROADMAP, 'utf8')).map((f) => ({
+        path: ROADMAP,
+        line: f.line,
+        message: f.message,
+        severity: 'error',
+    }));
+    console.log(`\ncheck:roadmap — le giornate dette in due posti\n`);
+    printFindings(findings, options.format);
+    if (findings.length === 0) {
+        console.log('  Tabella e sezioni concordano.\n');
+    }
+    else {
+        console.log('\n  Le giornate sono la fonte contrattuale: due numeri diversi sono uno sbagliato.\n');
+    }
+    return exitCode(findings, options.strict);
+}
+if (import.meta.main)
+    process.exit(main());

package/dist/checks/routes.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import { findingsFor, isScanned } from '../lib/check-routes.js';
+import { cliOptions, exitCode, printFindings, scopedPaths } from '../lib/cli.js';
+// 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) {
+    const options = cliOptions(args);
+    const paths = scopedPaths(options, isScanned);
+    const findings = [];
+    for (const path of paths)
+        for (const f of findingsFor(path, readFileSync(path, 'utf8')))
+            findings.push({ path, line: f.line, message: f.message, severity: 'error' });
+    const scope = options.diff ? ' (solo file toccati dal branch)' : '';
+    console.log(`\ncheck:routes — ${paths.length} documenti${scope}\n`);
+    printFindings(findings, options.format);
+    if (findings.length === 0) {
+        console.log('  Ogni rimando risolve.\n');
+    }
+    else {
+        console.log('\n  Un rimando morto non rompe niente: lo si scopre seguendolo, mesi dopo.\n');
+    }
+    return exitCode(findings, options.strict);
+}
+if (import.meta.main)
+    process.exit(main());

package/dist/checks/vercel-cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { 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';
+// Il documento `latest` porta la sola versione pubblicata; quello del pacchetto intero pesa 8 MB.
+const REGISTRY = 'https://registry.npmjs.org/vercel/latest';
+const TIMEOUT_MS = 15_000;
+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 { 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`);
+    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`);
+    return exitCode(findings, false);
+}
+if (import.meta.main)
+    process.exit(await main());

package/dist/lib/check-comments.js

@@ -0,0 +1,59 @@
+import { commentBlocks, styleOf } from './comment-syntax.js';
+import { PAST_TENSE } from './past-tense.js';
+const MAX_PROSE_LINES = 2;
+const NOISY_RATIO = 0.15;
+const MIN_LINES_FOR_RATIO = 40;
+// Direttive per strumenti: non sono prosa, non contano nella lunghezza del blocco né per il
+// tempo verbale.
+const KEEP = /biome-ignore|@ts-|\/\/\/\s*<reference|@vitest-environment|@vite-ignore|fallow-ignore|v8 ignore|c8 ignore|istanbul ignore|#__PURE__|SPDX-License-Identifier|TODO|FIXME|\[HARD\]|@public|@internal|@deprecated|^#!/;
+// Righe fatte solo di delimitatori: aprono o chiudono un blocco senza dire niente.
+const DELIMITER_ONLY = /^(?:\/\*+|\*+\/|\*|\{\/\*+|\*+\/\}|<!--|-->)$/;
+// Fuori: i file in cui il commento *è* il contenuto — in `.env.example` e `.npmrc` ogni riga
+// di prosa documenta la chiave sotto di sé.
+export const SCANNED = /\.(ts|tsx|astro|mjs|cjs|js|css|ya?ml|sh)$/;
+const isProse = (line) => !DELIMITER_ONLY.test(line.text.trim()) && !KEEP.test(line.text);
+// Un marcatore esenta la propria riga, mai il blocco: un solo `[HARD]` in mezzo comprerebbe
+// al commento lunghezza illimitata.
+function blockFinding(block) {
+    if (block.trailing)
+        return null;
+    const [first] = block.lines;
+    const prose = block.lines.filter(isProse).length;
+    if (!first || prose <= MAX_PROSE_LINES)
+        return null;
+    return {
+        line: first.n,
+        message: `blocco di ${prose} righe di prosa (max ${MAX_PROSE_LINES})`,
+    };
+}
+function pastTenseFinding(line) {
+    if (KEEP.test(line.text))
+        return null;
+    if (!PAST_TENSE.some((re) => re.test(line.text)))
+        return null;
+    return {
+        line: line.n,
+        message: `racconta il cambiamento: ${line.text.trim().slice(0, 60)}`,
+    };
+}
+export function report(file, lines) {
+    const findings = [];
+    let comments = 0;
+    for (const block of commentBlocks(lines, styleOf(file))) {
+        if (!block.trailing)
+            comments += block.lines.length;
+        const long = blockFinding(block);
+        if (long)
+            findings.push(long);
+        for (const line of block.lines) {
+            const narrated = pastTenseFinding(line);
+            if (narrated)
+                findings.push(narrated);
+        }
+    }
+    findings.sort((a, b) => a.line - b.line);
+    return { findings, comments, total: lines.length };
+}
+export function isNoisy({ comments, total }) {
+    return total >= MIN_LINES_FOR_RATIO && comments / total > NOISY_RATIO;
+}

package/dist/lib/check-language.js

@@ -0,0 +1,81 @@
+import { commentBlocks, styleOf } from './comment-syntax.js';
+import { ENGLISH, ITALIAN } from './language-words.js';
+const CODE = /^(?:(?:src|scripts|test|\.claude\/hooks|\.github)\/.*|[^/]+)\.(?:ts|tsx|astro|mjs|cjs|js|css|ya?ml|jsonc)$/;
+// Fuori le fonti del cliente (materiale altrui) e i changelog, generati in inglese.
+const DOCS = /^(?!docs\/sources\/)(?!(?:.*\/)?CHANGELOG\.md$).*\.md$/;
+// I dizionari sono copy per l'utente nelle lingue del sito: en e de leggono inglese e tedesco
+// per definizione, ed è il solo posto sotto CODE dove non deve leggersi italiano.
+const LOCALIZED = /^src\/i18n\/strings\//;
+// Sotto questa soglia il campione non dice niente: meglio indeciso che indovinato.
+const MIN_HITS = 4;
+// Un documento italiano che cita frasi inglesi non deve scattare: serve una maggioranza netta.
+const ENGLISH_SHARE = 0.6;
+// Inglese per costruzione, da togliere prima di contare: frontmatter, blocchi e span di
+// codice, URL, destinazioni dei link, riferimenti puntati (`this.cache`), chiamate, direttive.
+const NOISE = [
+    /^---\r?\n[\s\S]*?\r?\n---/,
+    /```[\s\S]*?```/g,
+    /`[^`\n]*`/g,
+    /https?:\/\/\S+/g,
+    /\]\([^)]*\)/g,
+    /[\w$]+(?:\.[\w$]+)+/g,
+    /[\w$]+\([^)]*\)/g,
+    /@[\w-]+/g,
+];
+export function isScanned(path) {
+    if (LOCALIZED.test(path))
+        return false;
+    return CODE.test(path) || DOCS.test(path);
+}
+function clean(prose) {
+    return NOISE.reduce((text, re) => text.replace(re, ' '), prose);
+}
+export function tally(prose) {
+    const text = clean(prose);
+    return {
+        italian: (text.match(ITALIAN) ?? []).length,
+        english: (text.match(ENGLISH) ?? []).length,
+    };
+}
+export function classify({ italian, english }, minHits = MIN_HITS) {
+    const hits = italian + english;
+    // Le liste di language-words.ts portano solo parole di una lingua sola: una inglese senza
+    // nessuna italiana decide anche un commento troppo corto per raggiungere MIN_HITS.
+    if (english > 0 && italian === 0)
+        return 'english';
+    if (hits < minHits)
+        return 'undecided';
+    return english / hits >= ENGLISH_SHARE ? 'english' : 'italian';
+}
+const describe = ({ english, italian }, sample) => `legge come inglese (en ${english} / it ${italian}): ${sample.replace(/\s+/g, ' ').trim().slice(0, 60)}`;
+const toLines = (source) => source.split('\n').map((text, i) => ({ n: i + 1, text }));
+/** In un sorgente la prosa sta solo nei commenti: il codice è inglese per costruzione. */
+export function findingsFor(path, source) {
+    if (!CODE.test(path)) {
+        const counts = tally(source);
+        return classify(counts) === 'english' ? [{ line: 1, message: describe(counts, source) }] : [];
+    }
+    const blocks = commentBlocks(toLines(source), styleOf(path));
+    const findings = [];
+    const total = { italian: 0, english: 0 };
+    for (const block of blocks) {
+        const [first] = block.lines;
+        const text = block.lines.map((line) => line.text).join('\n');
+        const counts = tally(text);
+        total.italian += counts.italian;
+        total.english += counts.english;
+        if (first && classify(counts) === 'english')
+            findings.push({
+                line: first.n,
+                message: describe(counts, text),
+            });
+    }
+    // Molti commenti brevi in inglese non fanno scattare nessun blocco da soli, ma insieme sì.
+    const firstLine = blocks[0]?.lines[0];
+    if (findings.length === 0 && classify(total) === 'english' && firstLine)
+        findings.push({
+            line: firstLine.n,
+            message: describe(total, 'nel complesso'),
+        });
+    return findings;
+}

package/dist/lib/check-placeholders.js

@@ -0,0 +1,56 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseEnv } from 'node:util';
+import { readLines } from './cli.js';
+const DICTIONARIES = 'src/i18n/strings';
+const CONTACT_ENV_KEYS = ['CONTACT_FROM_EMAIL', 'CONTACT_FROM_NAME', 'CONTACT_TO_EMAIL'];
+const TOKEN = /<[A-Z][A-Z_]{2,}>/;
+const DOMAIN = /\bexample\.com\b/;
+const STRING_LITERAL = /'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/g;
+const COMMENT_ONLY = /^\s*(?:\/\/|\/\*|\*)/;
+const ZERO_POSTAL_CODE = /\bpostalCode:\s*(['"])00000\1/;
+const EMPTY_HREF = /\bhref:\s*(['"])#\1/;
+export function placeholderSources() {
+    const dictionaries = readdirSync(DICTIONARIES)
+        .filter((name) => name.endsWith('.ts'))
+        .sort()
+        .map((name) => join(DICTIONARIES, name));
+    return ['src/lib/site.ts', 'src/lib/company.ts', ...dictionaries];
+}
+function literalFindings(value) {
+    const messages = [];
+    const token = value.match(TOKEN);
+    if (token)
+        messages.push(`segnaposto del template ${token[0]}`);
+    if (DOMAIN.test(value))
+        messages.push('dominio segnaposto example.com');
+    if (/^\+390+$/.test(value.replace(/\s/g, '')))
+        messages.push(`telefono segnaposto ${value}`);
+    return messages;
+}
+export function sourceFindings(source) {
+    return readLines(source).flatMap(({ n, text }) => {
+        if (COMMENT_ONLY.test(text))
+            return [];
+        const messages = [...text.matchAll(STRING_LITERAL)].flatMap((match) => literalFindings(match[0].slice(1, -1)));
+        if (ZERO_POSTAL_CODE.test(text))
+            messages.push('CAP segnaposto 00000');
+        if (EMPTY_HREF.test(text))
+            messages.push("profilo senza indirizzo: href: '#'");
+        return messages.map((message) => ({ line: n, message }));
+    });
+}
+export function envFindings(content) {
+    const env = parseEnv(content);
+    const lines = readLines(content);
+    return CONTACT_ENV_KEYS.flatMap((key) => {
+        const value = env[key]?.trim() ?? '';
+        const declaration = lines.find(({ text }) => new RegExp(`^\\s*${key}\\s*=`).test(text));
+        const at = declaration ? { line: declaration.n } : {};
+        if (value === '')
+            return [{ ...at, message: `${key} non è impostata: vale il default di astro.config.mjs` }];
+        if (TOKEN.test(value) || DOMAIN.test(value))
+            return [{ ...at, message: `${key} porta un segnaposto del template` }];
+        return [];
+    });
+}

package/dist/lib/check-roadmap.js

@@ -0,0 +1,124 @@
+/** «1,5» è una giornata e mezza. Una cella vuota non è zero giornate: `Number('')` sarebbe 0. */
+export function parseDays(raw) {
+    const text = raw.trim().replace(',', '.');
+    return text === '' ? Number.NaN : Number(text);
+}
+const cell = (row) => row.split('|').map((c) => c.trim());
+const ROW = /^\|\s*(\d+)\s*\|/;
+const SUBTOTAL = /^\|\s*\|\s*\*\*(FASE (\d+)[^*]*|TOTALE)\*\*/;
+const SECTION = /^## Milestone (\d+) — (.+)$/;
+const HEADER = /^\*\*Fase (\d+)\*\*\s*·\s*\*\*([\d,]+) gg\*\*/;
+/** Le righe numerate della tabella Status: una per milestone. */
+export function statusRows(source) {
+    const rows = [];
+    source.split('\n').forEach((line, i) => {
+        const match = ROW.exec(line);
+        if (!match?.[1])
+            return;
+        const cells = cell(line);
+        const number = Number(match[1]);
+        const name = cells[2];
+        const phase = Number(cells[3]);
+        const days = parseDays(cells[4] ?? '');
+        if (!name || Number.isNaN(phase) || Number.isNaN(days))
+            return;
+        rows.push({ line: i + 1, number, name, phase, days });
+    });
+    return rows;
+}
+/** Le righe di somma: un subtotale per fase, più il totale. */
+export function subtotals(source) {
+    const out = [];
+    source.split('\n').forEach((line, i) => {
+        const match = SUBTOTAL.exec(line);
+        if (!match?.[1])
+            return;
+        const days = parseDays((cell(line)[4] ?? '').replace(/\*/g, ''));
+        if (Number.isNaN(days))
+            return;
+        out.push({ line: i + 1, label: match[1], phase: match[2] ? Number(match[2]) : null, days });
+    });
+    return out;
+}
+/** Le sezioni `## Milestone N`, con la fase e le giornate della loro testata. */
+export function sections(source) {
+    const lines = source.split('\n');
+    const out = [];
+    lines.forEach((line, i) => {
+        const match = SECTION.exec(line);
+        if (!match?.[1] || !match[2])
+            return;
+        // La testata sta nelle righe subito sotto il titolo, dopo il riferimento alla Milestone GitHub.
+        const header = lines.slice(i, i + 6).find((l) => HEADER.test(l));
+        const parsed = header ? HEADER.exec(header) : null;
+        if (!parsed?.[1] || !parsed[2])
+            return;
+        out.push({
+            line: i + 1,
+            number: Number(match[1]),
+            name: match[2].trim(),
+            phase: Number(parsed[1]),
+            days: parseDays(parsed[2]),
+        });
+    });
+    return out;
+}
+const sum = (values) => Number(values.reduce((a, b) => a + b, 0).toFixed(2));
+/** I subtotali di fase e il totale devono essere la somma delle righe che coprono. */
+function totalsAgree(rows, totals) {
+    const findings = [];
+    for (const total of totals) {
+        const covered = total.phase === null ? rows : rows.filter((r) => r.phase === total.phase);
+        const expected = sum(covered.map((r) => r.days));
+        if (expected !== total.days)
+            findings.push({
+                line: total.line,
+                message: `${total.label}: la riga dice ${total.days} ma le milestone sommano ${expected}`,
+            });
+    }
+    return findings;
+}
+/** Ogni riga della tabella ha la sua sezione, e le due dicono le stesse giornate e la stessa fase. */
+function rowsAgree(rows, byNumber) {
+    const findings = [];
+    for (const row of rows) {
+        const section = byNumber.get(row.number);
+        if (!section) {
+            findings.push({ line: row.line, message: `milestone ${row.number} in tabella ma senza sezione` });
+            continue;
+        }
+        if (section.days !== row.days)
+            findings.push({
+                line: section.line,
+                message: `milestone ${row.number}: la tabella dice ${row.days} gg, la sezione ${section.days}`,
+            });
+        if (section.phase !== row.phase)
+            findings.push({
+                line: section.line,
+                message: `milestone ${row.number}: la tabella la mette in fase ${row.phase}, la sezione in fase ${section.phase}`,
+            });
+    }
+    return findings;
+}
+/** Una sezione che la tabella non elenca è lavoro che nessun totale conta. */
+function sectionsAreListed(rows, byNumber) {
+    const numbers = new Set(rows.map((r) => r.number));
+    return [...byNumber.values()]
+        .filter((section) => !numbers.has(section.number))
+        .map((section) => ({
+        line: section.line,
+        message: `milestone ${section.number} ha una sezione ma non è in tabella`,
+    }));
+}
+export function findingsFor(source) {
+    const rows = statusRows(source);
+    // Una roadmap ancora senza milestone è lo stato normale di un progetto appena nato.
+    if (rows.length === 0)
+        return [];
+    const byNumber = new Map(sections(source).map((s) => [s.number, s]));
+    return [
+        ...totalsAgree(rows, subtotals(source)),
+        ...rowsAgree(rows, byNumber),
+        ...sectionsAreListed(rows, byNumber),
+    ].sort((a, b) => a.line - b.line);
+}

package/dist/lib/check-routes.js

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from 'node:fs';
+const SCANNED = /\.md$/;
+const IGNORED = [
+    // Scritti a runtime dai comandi, gitignored per costruzione.
+    /^\.claude\/plans\//,
+    // Un PDF in docs/ è generato dai .md accanto, mai tracciato.
+    /\.pdf$/,
+    /^docs\/sources\//,
+];
+const PATH_REFERENCE = /`((?:docs|src|scripts|test|public|\.claude|\.github)\/[A-Za-z0-9._/-]+\.[a-z]+)`/g;
+// La virgola non delimita: i titoli la contengono.
+const SECTION_REFERENCE = /`([A-Za-z0-9._/-]+\.md)`\s*§\s*([^.·|)§]{1,80})/g;
+const isIgnored = (path) => IGNORED.some((re) => re.test(path));
+export const isScanned = (path) => SCANNED.test(path) && !isIgnored(path);
+export function normalizeTitle(raw) {
+    return (raw
+        .replace(/\*\*/g, '')
+        .replace(/`/g, '')
+        // Il marcatore non fa parte del nome: «Come si lavora [HARD]» si cita «Come si lavora».
+        .replace(/\s*\[[A-Z-]+\]\s*$/, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase());
+}
+export function headings(source) {
+    return source
+        .split('\n')
+        .filter((line) => /^#{2,4} /.test(line))
+        .map((line) => normalizeTitle(line.replace(/^#+\s*/, '')));
+}
+const resolves = (titles, cited) => titles.some((title) => cited === title || (cited.startsWith(title) && /^[^\p{L}\p{N}]/u.test(cited.slice(title.length))));
+export function resolveTarget(from, cited) {
+    if (cited.includes('/'))
+        return cited;
+    const sibling = `${from.slice(0, from.lastIndexOf('/') + 1)}${cited}`;
+    return existsSync(sibling) ? sibling : cited;
+}
+export function findingsFor(path, source) {
+    const findings = [];
+    // Un titolo va a capo come qualunque prosa: si cerca su testo continuo. La sostituzione è uno a
+    // uno, quindi gli offset restano quelli del sorgente e la riga si conta da lì.
+    const flat = source.replace(/\n/g, ' ');
+    const lineOf = (index) => source.slice(0, index).split('\n').length;
+    const missingTargets = new Set();
+    for (const match of flat.matchAll(PATH_REFERENCE)) {
+        const target = match[1];
+        if (!target || isIgnored(target) || target.includes('*') || existsSync(target))
+            continue;
+        missingTargets.add(target);
+        findings.push({ line: lineOf(match.index), message: `percorso che non esiste: ${target}` });
+    }
+    for (const match of flat.matchAll(SECTION_REFERENCE)) {
+        const [, file, title] = match;
+        /* v8 ignore next -- i due gruppi sono obbligatori nella regex, ma noUncheckedIndexedAccess pretende la guardia */
+        if (!file || !title)
+            continue;
+        const line = lineOf(match.index);
+        const target = resolveTarget(path, file);
+        if (isIgnored(target) || missingTargets.has(target))
+            continue;
+        if (!existsSync(target)) {
+            findings.push({ line, message: `sezione in un file che non esiste: ${target}` });
+            continue;
+        }
+        const cited = normalizeTitle(title);
+        if (!resolves(headings(readFileSync(target, 'utf8')), cited))
+            findings.push({ line, message: `sezione che non esiste: ${target} § ${cited}` });
+    }
+    return findings.sort((a, b) => a.line - b.line);
+}

package/dist/lib/cli.js

@@ -0,0 +1,56 @@
+import { existsSync } from 'node:fs';
+import process from 'node:process';
+import { parseArgs } from 'node:util';
+import { changedFiles, trackedAndUntracked } from './git.js';
+export function cliOptions(args = process.argv.slice(2)) {
+    const { GITHUB_ACTIONS } = process.env;
+    const { values } = parseArgs({
+        args,
+        options: {
+            diff: { type: 'boolean', default: false },
+            base: { type: 'string' },
+            head: { type: 'string' },
+            strict: { type: 'boolean', default: false },
+            format: {
+                type: 'string',
+                default: GITHUB_ACTIONS ? 'github' : 'text',
+            },
+        },
+    });
+    return { ...values, diff: values.diff || values.base !== undefined };
+}
+// Un file generato non lo scrive nessuno, e il suo banner chiede di tenerlo fuori da linter e
+// formatter: una correzione ai suoi commenti sparirebbe alla prima rigenerazione.
+export const isGenerated = (path) => /\.gen\.[cm]?tsx?$/.test(path);
+export function scopedPaths(options, isScanned) {
+    const candidates = options.diff ? changedFiles({ base: options.base, head: options.head }) : trackedAndUntracked();
+    // ls-files elenca anche i file cancellati ma non ancora rimossi dall'indice.
+    return candidates
+        .filter((path) => isScanned(path) && !isGenerated(path))
+        .filter(existsSync)
+        .sort();
+}
+// I workflow command di GitHub vogliono %, CR e LF codificati nel messaggio.
+const escapeForGitHub = (text) => text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+export function printFindings(findings, format) {
+    for (const finding of findings) {
+        const location = finding.line === undefined ? '' : `:${finding.line}`;
+        if (format === 'github') {
+            const lineParam = finding.line === undefined ? '' : `,line=${finding.line}`;
+            console.log(`::${finding.severity} file=${finding.path}${lineParam}::${escapeForGitHub(finding.message)}`);
+        }
+        else {
+            const mark = finding.severity === 'error' ? '✗' : '·';
+            console.log(`  ${mark} ${finding.path}${location}: ${finding.message}`);
+        }
+    }
+}
+export function exitCode(findings, strict) {
+    const hasErrors = findings.some((f) => f.severity === 'error');
+    const hasWarnings = findings.some((f) => f.severity === 'warning');
+    return hasErrors || (strict && hasWarnings) ? 1 : 0;
+}
+export const readLines = (text) => text
+    .replace(/\r?\n$/, '')
+    .split(/\r?\n/)
+    .map((line, i) => ({ n: i + 1, text: line }));

package/dist/lib/comment-syntax.js

@@ -0,0 +1,96 @@
+const HASH_STYLE = /\.(ya?ml|sh)$/;
+const CSS_STYLE = /\.css$/;
+const ASTRO_STYLE = /\.astro$/;
+export function styleOf(file) {
+    if (HASH_STYLE.test(file))
+        return 'hash';
+    if (CSS_STYLE.test(file))
+        return 'css';
+    return ASTRO_STYLE.test(file) ? 'astro' : 'slash';
+}
+// Ritorna [chiusura attesa, lunghezza dell'apertura] se la riga apre un commento; chiusura
+// vuota per i commenti a riga singola.
+function opener(s, style) {
+    if (style === 'hash')
+        return s.startsWith('#') && !s.startsWith('#!') ? ['', 1] : null;
+    if (style !== 'css' && s.startsWith('//'))
+        return ['', 2];
+    if (s.startsWith('{/*'))
+        return ['*/}', 3];
+    if (s.startsWith('/*'))
+        return ['*/', 2];
+    if (style === 'astro' && s.startsWith('<!--'))
+        return ['-->', 4];
+    return null;
+}
+// Gli indici dei caratteri che stanno fuori da una stringa. Percorrere la riga è l'unico modo:
+// contare le virgolette non regge un apostrofo ("L'esperienza") né un escape.
+function* outsideStrings(text) {
+    let quote = '';
+    for (let i = 0; i < text.length; i++) {
+        const ch = text.charAt(i);
+        if (quote) {
+            if (ch === '\\')
+                i++;
+            else if (ch === quote)
+                quote = '';
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === '`') {
+            quote = ch;
+            continue;
+        }
+        // Fuori dalle stringhe un backslash sta solo nelle regex: "\\/\\/" non è un commento.
+        if (ch === '\\') {
+            i++;
+            continue;
+        }
+        yield i;
+    }
+}
+// In YAML e shell "#" apre un commento solo dopo uno spazio: "url#frag" è un valore.
+const opensComment = (text, i, style) => style === 'hash'
+    ? text.charAt(i) === '#' && /\s/.test(text.charAt(i - 1))
+    : text.charAt(i) === '/' && (text[i + 1] === '/' || text[i + 1] === '*');
+// Il commento in coda a una riga di codice, se c'è.
+function trailingComment(text, style) {
+    if (style === 'css')
+        return null;
+    for (const i of outsideStrings(text))
+        if (i > 0 && opensComment(text, i, style))
+            return text.slice(i);
+    return null;
+}
+export function commentBlocks(lines, style) {
+    const blocks = [];
+    let current = [];
+    let closer = '';
+    const flush = () => {
+        if (current.length > 0)
+            blocks.push({ lines: current, trailing: false });
+        current = [];
+    };
+    for (const line of lines) {
+        const s = line.text.trim();
+        if (closer) {
+            current.push(line);
+            if (s.includes(closer))
+                closer = '';
+            continue;
+        }
+        const opened = opener(s, style);
+        if (opened) {
+            const [expected, skip] = opened;
+            current.push(line);
+            if (expected && s.indexOf(expected, skip) === -1)
+                closer = expected;
+            continue;
+        }
+        flush();
+        const trailing = trailingComment(line.text, style);
+        if (trailing)
+            blocks.push({ lines: [{ n: line.n, text: trailing }], trailing: true });
+    }
+    flush();
+    return blocks;
+}

package/dist/lib/git.js

@@ -0,0 +1,76 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import process from 'node:process';
+function git(args, { allowFailure = false } = {}) {
+    const result = spawnSync('git', args, { encoding: 'utf8' });
+    if (result.status !== 0) {
+        if (allowFailure)
+            return '';
+        throw new Error(result.stderr.trim() || `git ${args.join(' ')} fallito`);
+    }
+    return result.stdout;
+}
+// Senza -z git cita ed escapa i path non ASCII ("docs/\303\250.md"): existsSync non li trova
+// e il file sparisce dalla passata senza errori.
+const gitPaths = (subcommand, args) => git([subcommand, '-z', ...args])
+    .split('\0')
+    .filter(Boolean);
+export const trackedAndUntracked = () => [
+    ...gitPaths('ls-files', []),
+    ...gitPaths('ls-files', ['--others', '--exclude-standard']),
+];
+function ensureCommit(ref) {
+    const exists = spawnSync('git', ['cat-file', '-e', `${ref}^{commit}`], {
+        stdio: 'ignore',
+    });
+    if (exists.status === 0)
+        return;
+    // Checkout shallow in CI: la base della PR spesso non c'è in locale.
+    git(['fetch', '--no-tags', 'origin', ref]);
+}
+function defaultBase() {
+    const originHead = git(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], {
+        allowFailure: true,
+    }).trim();
+    if (originHead)
+        return originHead;
+    for (const candidate of ['origin/main', 'main', 'origin/master', 'master']) {
+        if (git(['rev-parse', '--verify', '--quiet', candidate], {
+            allowFailure: true,
+        }).trim())
+            return candidate;
+    }
+    throw new Error('nessuna base trovata: passa --base <ref>');
+}
+// Sulle PR GitHub il diff va fatto tra gli SHA dell'evento, non tra branch locali.
+function pullRequestShas() {
+    const { GITHUB_EVENT_NAME, GITHUB_EVENT_PATH } = process.env;
+    if (GITHUB_EVENT_NAME !== 'pull_request' || !GITHUB_EVENT_PATH || !existsSync(GITHUB_EVENT_PATH))
+        return undefined;
+    const { pull_request: pr } = JSON.parse(readFileSync(GITHUB_EVENT_PATH, 'utf8'));
+    return pr?.base?.sha && pr?.head?.sha ? { base: pr.base.sha, head: pr.head.sha } : undefined;
+}
+export function changedFiles({ base, head }) {
+    const pr = base ? undefined : pullRequestShas();
+    const from = base ?? pr?.base ?? defaultBase();
+    const to = head ?? pr?.head ?? 'HEAD';
+    ensureCommit(from);
+    ensureCommit(to);
+    let committed;
+    try {
+        committed = gitPaths('diff', ['--name-only', '--diff-filter=ACMR', `${from}...${to}`]);
+    }
+    catch (error) {
+        throw new Error(`diff ${from}...${to} fallito (clone shallow? prova "git fetch --unshallow"): ${error.message}`);
+    }
+    // In locale contano anche le modifiche non ancora committate; con un head esplicito o in PR no.
+    const includeWorkingTree = !pr && !head;
+    const workingTree = includeWorkingTree
+        ? [
+            ...gitPaths('diff', ['--name-only', '--diff-filter=ACMR']),
+            ...gitPaths('diff', ['--cached', '--name-only', '--diff-filter=ACMR']),
+            ...gitPaths('ls-files', ['--others', '--exclude-standard']),
+        ]
+        : [];
+    return [...new Set([...committed, ...workingTree])];
+}

package/dist/lib/language-words.js

@@ -0,0 +1,157 @@
+// \b è ASCII: "già", "perché" e "è" con \b non matchano mai. Il trattino nei confini esclude
+// "non-null" e "un-styled" dal conteggio italiano.
+const words = (list) => new RegExp(`(?<![\\p{L}\\p{N}-])(?:${list.join('|')})(?![\\p{L}\\p{N}-])`, 'giu');
+// Solo parole funzione di una lingua sola: fuori "per" (per request), "in", "a", "come",
+// "solo", "so", "no", "all" (all'inizio).
+export const ITALIAN = words([
+    'è',
+    'che',
+    'non',
+    'il',
+    'la',
+    'lo',
+    'le',
+    'gli',
+    'un',
+    'una',
+    'uno',
+    'di',
+    'da',
+    'su',
+    'se',
+    'ma',
+    'più',
+    'già',
+    'poi',
+    'qui',
+    'mai',
+    'cui',
+    'dove',
+    'del',
+    'dello',
+    'della',
+    'delle',
+    'degli',
+    'dei',
+    'dal',
+    'dalla',
+    'dalle',
+    'dagli',
+    'dai',
+    'nel',
+    'nello',
+    'nella',
+    'nelle',
+    'negli',
+    'nei',
+    'sul',
+    'sulla',
+    'sulle',
+    'sui',
+    'al',
+    'allo',
+    'alla',
+    'alle',
+    'agli',
+    'ai',
+    'con',
+    'senza',
+    'ogni',
+    'anche',
+    'quindi',
+    'perché',
+    'sono',
+    'viene',
+    'vengono',
+    'essere',
+    'può',
+    'deve',
+    'devono',
+    'possono',
+    'fatto',
+    'questo',
+    'questa',
+    'questi',
+    'queste',
+    'quello',
+    'quella',
+    'quando',
+    'mentre',
+    'invece',
+    'oppure',
+    'però',
+    'sempre',
+    'tutti',
+    'tutte',
+    'tutto',
+    'stesso',
+    'stessa',
+    'cosa',
+    'così',
+]);
+export const ENGLISH = words([
+    'the',
+    'and',
+    'that',
+    'with',
+    'from',
+    'this',
+    'these',
+    'those',
+    'is',
+    'are',
+    'was',
+    'were',
+    'be',
+    'been',
+    'have',
+    'has',
+    'had',
+    'of',
+    'to',
+    'for',
+    'on',
+    'at',
+    'by',
+    'or',
+    'as',
+    'if',
+    'not',
+    'it',
+    'its',
+    'we',
+    'you',
+    'they',
+    'their',
+    'our',
+    'your',
+    'an',
+    'when',
+    'only',
+    'also',
+    'already',
+    'every',
+    'each',
+    'any',
+    'some',
+    'more',
+    'most',
+    'but',
+    'which',
+    'what',
+    'does',
+    'without',
+    'because',
+    'will',
+    'should',
+    'can',
+    'must',
+    'use',
+    'used',
+    'using',
+    'into',
+    'than',
+    'then',
+    'there',
+    'here',
+]);

package/dist/lib/past-tense.js

@@ -0,0 +1,19 @@
+// \b è ASCII anche con il flag u: "\bpiù\b" e "\bgià\b" non matchano mai. I confini di parola
+// vanno scritti a mano con \p{L}.
+const phrase = (alternatives) => new RegExp(`(?<![\\p{L}\\p{N}])(?:${alternatives.join('|')})(?![\\p{L}\\p{N}])`, 'iu');
+export const PAST_TENSE = [
+    phrase([
+        "prima (?:era|c'era|veniva|faceva|andava|lo|si)",
+        'in precedenza',
+        'una volta era',
+        'era stato',
+        'in passato',
+        'storicamente',
+    ]),
+    // "non più di 3" è una quantità, non un cambiamento.
+    phrase(['non (?:è |viene |serve )?più(?! di)']),
+    phrase(["ora (?:è|invece|lo|la|il|si|c'è|non)", 'adesso', 'per ora', 'temporaneamente']),
+    phrase(['sostituisce', 'al posto di', 'vecchi[oa]']),
+    phrase(['used to', 'previously', 'no longer', 'replaces the', 'replaced by', 'removed in', 'for now', 'temporarily']),
+    /#\d{1,3}(?!\d)/,
+];

package/dist/lib/vercel-cli-pin.js

@@ -0,0 +1,29 @@
+import { readLines } from './cli.js';
+const PIN = /\bvercel@(\d+)\b/;
+function pinnedVersions(workflow) {
+    return readLines(workflow).flatMap(({ n, text }) => {
+        const major = Number(PIN.exec(text)?.[1]);
+        return Number.isNaN(major) ? [] : [{ line: n, major }];
+    });
+}
+function publishedMajor(version) {
+    return Number(/^\s*(\d+)\./.exec(version)?.[1]);
+}
+export function pinFindings(workflow, latest) {
+    const pins = pinnedVersions(workflow);
+    if (pins.length === 0)
+        return [{ line: 1, message: 'nessun `vercel@<major>`: il pin è sparito dal workflow' }];
+    const majors = [...new Set(pins.map(({ major }) => major))].sort((a, b) => a - b);
+    if (majors.length > 1)
+        return pins.map(({ line, major }) => ({
+            line,
+            message: `vercel@${major}: il workflow porta major diverse (${majors.join(', ')})`,
+        }));
+    const published = publishedMajor(latest);
+    if (Number.isNaN(published))
+        return [{ line: 1, message: `versione pubblicata illeggibile: ${JSON.stringify(latest)}` }];
+    const pinned = Math.max(...pins.map(({ major }) => major));
+    if (pinned >= published)
+        return [];
+    return pins.map(({ line }) => ({ line, message: `vercel@${pinned}: su npm è pubblicata la major ${published}` }));
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@elia97/officina",
+  "version": "0.1.0",
+  "description": "Gli strumenti dei progetti nati dai template di Elia: gate di qualità e, più avanti, generatori.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Elia97/officina.git"
+  },
+  "bin": {
+    "officina": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.10",
+    "@types/node": "^24.13.5",
+    "@vitest/coverage-v8": "^4.1.11",
+    "fallow": "^3.26.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "format": "biome check --write .",
+    "check:deadcode": "fallow dead-code",
+    "check:health": "fallow health --complexity --coverage coverage/coverage-final.json",
+    "ci": "biome ci --error-on-warnings . && pnpm run typecheck && pnpm run check:deadcode && pnpm run test && pnpm run check:health"
+  }
+}