@elia97/officina 0.4.0 → 0.5.0

package/dist/lib/tooling.js

@@ -0,0 +1,24 @@
+import { peerRange, withinRange } from './versions.js';
+// Strumenti che i preset e le action danno per scontati: senza, il progetto sembra allineato e poi
+// il primo commit o il primo job li cerca e non li trova.
+const REQUIRED = [
+    { name: '@biomejs/biome', reason: 'il progetto estende `@elia97/officina/biome`' },
+    { name: 'lefthook', reason: 'il preset dei git hook è suo, e `prepare` lo installa' },
+    { name: '@commitlint/cli', reason: 'il preset di lefthook lo lancia su ogni messaggio di commit' },
+    { name: '@commitlint/config-conventional', reason: 'è la configurazione che commitlint estende' },
+    { name: 'fallow', reason: '`check:deadcode` e `check:health` lo lanciano' },
+];
+const BIOME = '@biomejs/biome';
+const MANIFEST = 'package.json';
+// Il preset usa una regola `nursery`, che fra una major e l'altra di Biome cambia nome o sparisce:
+// l'intervallo che regge lo dichiara il pacchetto, in un posto solo.
+function biomeRangeGap(declared) {
+    const range = peerRange(BIOME);
+    return withinRange(declared, range) ? undefined : `\`${BIOME}\` è \`${declared}\`: il preset regge \`${range}\``;
+}
+export function toolingGaps({ devDependencies = {} }) {
+    const gaps = REQUIRED.filter(({ name }) => devDependencies[name] === undefined).map(({ name, reason }) => ({ path: MANIFEST, message: `\`${name}\` non è fra le devDependencies: ${reason}` }));
+    const biome = devDependencies[BIOME];
+    const range = biome === undefined ? undefined : biomeRangeGap(biome);
+    return range === undefined ? gaps : [...gaps, { path: MANIFEST, message: range }];
+}

package/dist/lib/validate.d.ts

@@ -0,0 +1,11 @@
+export type Check = (value: unknown, path: string) => string[];
+export declare function typeName(value: unknown): string;
+export declare const problem: (path: string, expected: string, value: unknown) => string;
+export declare const aString: Check;
+export declare const aNumber: Check;
+export declare const aFunction: Check;
+export declare const aStringOrNull: Check;
+export declare const anArrayOf: (item: Check) => Check;
+export declare const aRecordOf: (item: Check) => Check;
+export declare const oneOf: (expected: string, allowed: readonly unknown[]) => Check;
+export declare const aShape: (fields: Record<string, Check>) => Check;

package/dist/lib/validate.js

@@ -0,0 +1,40 @@
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const NAMES = new Map([
+    ['string', 'una stringa'],
+    ['number', 'un numero'],
+    ['boolean', 'un booleano'],
+    ['function', 'una funzione'],
+    ['undefined', 'niente'],
+]);
+export function typeName(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'un array';
+    return NAMES.get(typeof value) ?? 'un oggetto';
+}
+export const problem = (path, expected, value) => `${path}: atteso ${expected}, ricevuto ${typeName(value)}`;
+export const aString = (value, path) => (typeof value === 'string' ? [] : [problem(path, 'una stringa', value)]);
+export const aNumber = (value, path) => (typeof value === 'number' ? [] : [problem(path, 'un numero', value)]);
+export const aFunction = (value, path) => typeof value === 'function' ? [] : [problem(path, 'una funzione', value)];
+export const aStringOrNull = (value, path) => typeof value === 'string' || value === null ? [] : [problem(path, 'una stringa oppure null', value)];
+export const anArrayOf = (item) => (value, path) => Array.isArray(value)
+    ? value.flatMap((entry, index) => item(entry, `${path}[${index}]`))
+    : [problem(path, 'un array', value)];
+export const aRecordOf = (item) => (value, path) => isRecord(value)
+    ? Object.entries(value).flatMap(([key, entry]) => item(entry, `${path}.${key}`))
+    : [problem(path, 'un oggetto', value)];
+export const oneOf = (expected, allowed) => (value, path) => allowed.includes(value) ? [] : [problem(path, expected, value)];
+// Una voce non dichiarata è un errore: `sitUrl` al posto di `siteUrl` non deve passare in
+// silenzio, che è il modo esatto in cui una configurazione smette di dire qualcosa.
+export const aShape = (fields) => (value, path) => {
+    if (!isRecord(value))
+        return [problem(path, 'un oggetto', value)];
+    const prefix = path === '' ? '' : `${path}.`;
+    return Object.entries(value).flatMap(([key, entry]) => {
+        const check = fields[key];
+        if (check === undefined)
+            return [`${prefix}${key}: voce sconosciuta`];
+        return entry === undefined ? [] : check(entry, `${prefix}${key}`);
+    });
+};

package/dist/lib/versions.d.ts

@@ -0,0 +1,5 @@
+export declare const packageVersion: () => string;
+/** L'intervallo che il pacchetto dichiara di reggere: sta in un posto solo, le sue peerDependencies. */
+export declare const peerRange: (name: string) => string;
+/** Vero solo se ogni versione che `spec` può installare sta dentro `range`, scritto `>=x.y.z <a.b.c`. */
+export declare function withinRange(spec: string, range: string): boolean;

package/dist/lib/versions.js

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const self = () => JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
+export const packageVersion = () => self().version;
+/** L'intervallo che il pacchetto dichiara di reggere: sta in un posto solo, le sue peerDependencies. */
+export const peerRange = (name) => self().peerDependencies?.[name] ?? '';
+const EXACT = /(\d+)\.(\d+)\.(\d+)/;
+function parseVersion(text) {
+    const found = EXACT.exec(text);
+    return found === null ? undefined : [Number(found[1]), Number(found[2]), Number(found[3])];
+}
+const compare = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+// Il limite superiore escluso di ciò che lo specificatore può installare: `^` sale fino alla major
+// dopo (fino alla minor dopo, sotto lo zero), `~` fino alla minor dopo, una versione esatta a sé.
+function ceiling(spec, [major, minor, patch]) {
+    if (spec.startsWith('^'))
+        return major === 0 ? [0, minor + 1, 0] : [major + 1, 0, 0];
+    if (spec.startsWith('~'))
+        return [major, minor + 1, 0];
+    return EXACT.test(spec.replace(/^[=v]/, '')) && !/[<>|*x\s]/.test(spec) ? [major, minor, patch + 1] : undefined;
+}
+function parseBounds(range) {
+    const [low = '', high = '', extra] = range.split(' ');
+    if (extra !== undefined || !low.startsWith('>=') || !high.startsWith('<'))
+        return undefined;
+    const min = parseVersion(low);
+    const max = parseVersion(high);
+    return min === undefined || max === undefined ? undefined : { min, max };
+}
+/** Vero solo se ogni versione che `spec` può installare sta dentro `range`, scritto `>=x.y.z <a.b.c`. */
+export function withinRange(spec, range) {
+    const bounds = parseBounds(range);
+    const floor = parseVersion(spec);
+    if (bounds === undefined || floor === undefined)
+        return false;
+    const top = ceiling(spec, floor);
+    return top === undefined ? false : compare(floor, bounds.min) >= 0 && compare(top, bounds.max) <= 0;
+}

package/dist/lib/workflows.d.ts

@@ -0,0 +1,6 @@
+import type { ProjectFiles } from './alignment.ts';
+import type { ContractGap } from './contract.ts';
+export declare const mentions: (source: string | undefined, needle: string) => boolean;
+/** Le action del progetto devono stare alla stessa versione del pacchetto installato. */
+export declare function workflowGaps({ read }: ProjectFiles, version: string): ContractGap[];
+export declare function dependabotGaps({ read }: ProjectFiles): ContractGap[];

package/dist/lib/workflows.js

@@ -0,0 +1,70 @@
+// I workflow restano una ricerca testuale — non c'è un parser YAML nel pacchetto — ma una riga
+// commentata non deve soddisfare niente: è il modo più facile per avere un progetto «a posto»
+// che in CI non lancia nessuno di questi passi.
+const liveLines = (source) => source.split(/\r?\n/).filter((line) => !line.trimStart().startsWith('#'));
+export const mentions = (source, needle) => source !== undefined && liveLines(source).some((line) => line.includes(needle));
+const ACTIONS = [
+    { workflow: '.github/workflows/ci.yml', action: 'ci' },
+    { workflow: '.github/workflows/ci.yml', action: 'review' },
+    { workflow: '.github/workflows/deploy.yml', action: 'deploy' },
+    { workflow: '.github/workflows/lighthouse.yml', action: 'lighthouse' },
+];
+// Un tag di versione o uno SHA intero: `@main` farebbe girare in produzione passi mai collaudati.
+const TAG = /^v\d+\.\d+\.\d+$/;
+const SHA = /^[0-9a-f]{40}$/;
+const COMMENTED_VERSION = /#\s*(v\d+\.\d+\.\d+)/;
+function refOf(source, name) {
+    const pattern = new RegExp(`${name}@(\\S+)`);
+    for (const line of liveLines(source)) {
+        const ref = pattern.exec(line)?.[1];
+        if (ref !== undefined)
+            return { line, ref };
+    }
+    return undefined;
+}
+function refGap(line, ref, name, expected) {
+    if (TAG.test(ref)) {
+        return ref === expected ? undefined : `\`${name}@${ref}\`: il pacchetto installato è la ${expected.slice(1)}`;
+    }
+    if (!SHA.test(ref))
+        return `\`${name}@${ref}\`: il riferimento va fissato a un tag di versione o a uno SHA`;
+    const declared = COMMENTED_VERSION.exec(line)?.[1];
+    if (declared === undefined) {
+        return `\`${name}@${ref.slice(0, 7)}…\`: uno SHA non dice che versione è — scrivila nel commento (\`# ${expected}\`)`;
+    }
+    return declared === expected
+        ? undefined
+        : `\`${name}@${ref.slice(0, 7)}… ${declared}\`: il pacchetto installato è la ${expected.slice(1)}`;
+}
+function actionGap(source, action, version) {
+    const name = `Elia97/officina/actions/${action}`;
+    if (source === undefined)
+        return `manca: i suoi passi arrivano da \`${name}\``;
+    const found = refOf(source, name);
+    return found === undefined ? `non usa \`${name}\`` : refGap(found.line, found.ref, name, `v${version}`);
+}
+/** Le action del progetto devono stare alla stessa versione del pacchetto installato. */
+export function workflowGaps({ read }, version) {
+    return ACTIONS.flatMap(({ workflow, action }) => {
+        const message = actionGap(read(workflow), action, version);
+        return message === undefined ? [] : [{ path: workflow, message }];
+    });
+}
+const DEPENDABOT = '.github/dependabot.yml';
+// Senza il gruppo, Dependabot apre due PR — una per il pacchetto npm, una per le action — e il
+// controllo di coerenza qui sopra le boccia entrambe, perché nessuna delle due allinea l'altra.
+const GROUPED = [
+    { needle: 'multi-ecosystem-groups', reason: 'il pacchetto e le sue action si alzano in una PR sola' },
+    { needle: '@elia97/officina', reason: 'il gruppo deve prendere il pacchetto da npm' },
+    { needle: 'Elia97/officina/*', reason: 'il gruppo deve prendere le action da github-actions' },
+];
+export function dependabotGaps({ read }) {
+    const source = read(DEPENDABOT);
+    if (source === undefined) {
+        return [{ path: DEPENDABOT, message: 'manca: senza, il pacchetto e le sue action si alzano separati' }];
+    }
+    return GROUPED.filter(({ needle }) => !mentions(source, needle)).map(({ needle, reason }) => ({
+        path: DEPENDABOT,
+        message: `non nomina \`${needle}\`: ${reason}`,
+    }));
+}

package/dist/sh/lhci-local.sh

@@ -38,7 +38,7 @@ SERVER_PID=''
 cleanup() {
   if [[ -n "${SERVER_PID}" ]]; then
     kill -- "-${SERVER_PID}" 2>/dev/null || kill "${SERVER_PID}" 2>/dev/null || true
-    pkill -f "serve@14 .*--listen ${PORT}" 2>/dev/null || true
+    pkill -f "serve@14.2.6 .*--listen ${PORT}" 2>/dev/null || true
   fi
   find . -maxdepth 1 \( -name '*wsl.localhost*' -o -name 'undefined*' \) -exec rm -rf {} + 2>/dev/null || true
 }
@@ -55,7 +55,7 @@ fi
 echo "✓ robots.txt: Allow: /"
 
 echo "→ avvio del server statico su :${PORT}"
-setsid pnpm dlx serve@14 "${OUT_DIR}/client" --listen "${PORT}" --no-clipboard >/dev/null 2>&1 &
+setsid pnpm dlx serve@14.2.6 "${OUT_DIR}/client" --listen "${PORT}" --no-clipboard >/dev/null 2>&1 &
 SERVER_PID=$!
 
 for _ in $(seq 1 60); do

package/dist/smoke.d.ts

@@ -0,0 +1,2 @@
+export { NON_HTML_ROUTES } from './lib/routes.ts';
+export { checkBotIdChallenge, checkCanonicalHost, checkPages, checkSecurityHeaders, checkTrailingSlash, DEFAULT_CHECKS, SECURITY_HEADERS, } from './lib/smoke-production.ts';

package/dist/smoke.js

@@ -0,0 +1,4 @@
+// I pezzi con cui un progetto compone i propri controlli di smoke: `smoke.checks` sostituisce la
+// lista del pacchetto, quindi chi ne toglie uno ricompone la lista da qui.
+export { NON_HTML_ROUTES } from './lib/routes.js';
+export { checkBotIdChallenge, checkCanonicalHost, checkPages, checkSecurityHeaders, checkTrailingSlash, DEFAULT_CHECKS, SECURITY_HEADERS, } from './lib/smoke-production.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elia97/officina",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Gli strumenti dei progetti nati dai template di Elia: gate di qualità, generatori e verifiche di build e di produzione.",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,18 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./smoke": {
+      "types": "./dist/smoke.d.ts",
+      "default": "./dist/smoke.js"
+    },
+    "./bundle": {
+      "types": "./dist/bundle.d.ts",
+      "default": "./dist/bundle.js"
+    },
+    "./icons": {
+      "types": "./dist/icons.d.ts",
+      "default": "./dist/icons.js"
+    },
     "./biome": "./presets/biome.base.json"
   },
   "bin": {
@@ -24,11 +36,23 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=24.2.0"
   },
+  "packageManager": "pnpm@11.22.0",
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp -r src/gen/templates dist/gen/templates && cp -r src/sh dist/sh",
+    "prepack": "pnpm run build",
+    "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",
+    "test:pack": "bash scripts/pack-test.sh"
+  },
   "devDependencies": {
     "@biomejs/biome": "2.5.10",
     "@types/node": "^24.13.5",
@@ -42,20 +66,12 @@
     "ts-morph": "^28.0.0"
   },
   "peerDependencies": {
+    "@biomejs/biome": ">=2.5.10 <3.0.0",
     "sharp": ">=0.34.0"
   },
   "peerDependenciesMeta": {
     "sharp": {
       "optional": true
     }
-  },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp -r src/gen/templates dist/gen/templates && cp -r src/sh dist/sh",
-    "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"
   }
-}
+}

package/dist/lib/vercel-cli-pin.d.ts

@@ -1,2 +0,0 @@
-import { type Hit } from './cli.ts';
-export declare function pinFindings(workflow: string, latest: string): Hit[];

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

@@ -1,29 +0,0 @@
-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}` }));
-}