@elia97/officina 0.12.0 → 0.13.0

package/README.md

@@ -46,7 +46,7 @@ I gate leggono dalla cartella corrente, che deve essere la radice del repository
 
 | Comando | Cosa guarda | Da dove prende le rotte |
 |---|---|---|
-| `check bundle` | il JavaScript e il CSS di `dist/client`, gzip, contro un budget per rotta | `src/pages`; sotto SSR, il manifest della build Vercel |
+| `check bundle` | il JavaScript e il CSS di `dist/client`, gzip, contro un budget per rotta; nel CSS, le media query in sintassi di intervallo | `src/pages`; sotto SSR, il manifest della build Vercel |
 | `check links` | gli `<a href>` di `dist/client`: ogni link interno porta a qualcosa che la build serve, e nessuno a `#` | i file di `dist/client` e le rotte a richiesta del manifest della build Vercel |
 | `check secrets [--canaries]` | i file di `dist/client`: nessuno contiene il valore o il canary di una chiave server e secret di `env.schema` | — |
 | `check smoke [url]` | la produzione viva: pagine, pagine rese a richiesta, header di sicurezza, BotID, host canonico, barra finale | `src/pages`, più le rotte non HTML |
@@ -58,6 +58,16 @@ Gli script di una pagina statica si leggono dal suo HTML, anche sotto una `base`
 
 Il CSS di una rotta è la somma dei fogli di `dist/client/_astro` che collega, ognuno contato una volta: per una pagina statica i `<link rel="stylesheet">` del suo HTML, anche sotto una `base`, da un `assetsPrefix` o con una query; per una rotta renderizzata a richiesta i fogli esterni che il manifest le assegna, e una rotta per cui il manifest non li dice è un fallimento. Il tetto è `bundle.cssMaxGzip`, e il rapporto ha una riga per ogni combinazione di fogli, perché le rotte che collegano gli stessi fogli pesano uguale. Non si contano il CSS dentro l'HTML, nei `<style>`, come il JavaScript incorporato, i link che non bloccano il rendering (`preload`, `prefetch`) e i fogli fuori da `_astro`, da `public/` o da un CDN. Un foglio citato che in `_astro` non c'è è un fallimento. Un foglio che nessuna rotta misurata collega si pesa da solo contro lo stesso tetto, e nel rapporto porta «da solo»: il CSS di un `import()` dinamico, quello dei componenti dentro un contenuto MDX reso a richiesta, che il manifest non assegna alla pagina, o tutti i fogli di una build le cui rotte non si leggono. Da solo pesa meno del vero, ma nessun foglio oltre il tetto passa in silenzio.
 
+Il CSS costruito non deve contenere media query in sintassi di intervallo, come `@media (width>=40rem)`. Safari le legge solo dalla 16.4, e un Safari più vecchio ignora la regola intera: un sito scritto mobile-first si impagina come su un telefono. Le lascia Lightning CSS, che minifica il CSS della build, quando non sa per quali browser scrive: Astro 7 costruisce con `build.target: 'esnext'`, Vite 8 ne ricava `cssTarget`, e il minificatore non abbassa la sintassi e toglie anche i prefissi, come `-webkit-backdrop-filter`. Nessun browser recente mostra il difetto, e `astro dev` non minifica: si vede solo nel CSS costruito. `check bundle` legge i fogli di `dist/client/_astro` e i `<style>` dell'HTML delle pagine, dove Astro mette i fogli piccoli, e fallisce su ogni media query con un confronto nel preludio, `<`, `>` o `=`, i segni che soltanto la sintassi di intervallo usa; i commenti non contano, e il rapporto nomina il file e le query. Restano fuori le query di `@container`, i fogli fuori da `_astro`, i `<style>` delle pagine rese a richiesta, che nella build non hanno HTML, e i prefissi tolti, che il controllo non vede.
+
+Il controllo non si spegne, e fallisce dalla versione che lo porta, senza un giro di avvisi: un progetto senza `cssTarget` ha già il difetto, e la correzione è una riga in `astro.config.mjs`, con i browser che il progetto sostiene. `min-width` e `max-width` sono la stessa query in ogni browser, quindi abbassare non costa niente.
+
+```js
+export default defineConfig({
+  vite: { build: { cssTarget: ['chrome111', 'edge111', 'firefox114', 'safari15.4', 'ios15.4'] } },
+})
+```
+
 `check links` legge gli `<a href>` di ogni HTML di `dist/client`, fuori dai commenti, dagli `<script>`, dagli `<style>` e dai valori degli attributi, dove Astro lascia `<` e `>` come sono. È interno un link relativo, uno che comincia con `/` o uno assoluto verso l'origine di `siteUrl`, e se ne confronta il percorso, senza query né ancora, con o senza barra finale; un link relativo si risolve come con `trailingSlash: 'never'`, che è quello dei template. Vale se porta a un file della build, pagina o altro file, o a una rotta che il manifest della build Vercel rende a richiesta, endpoint e `/` di lingua compresi, confrontata con il pattern che Astro scrive lì; senza manifest, o con un altro adapter, a una pagina `.astro` con `prerender = false`, e il rapporto lo dice. Che la pagina dietro una rotta a richiesta esista lo sa solo il server, e una rotta come `/[...slug]` accetta ogni percorso: il rapporto conta i link che passano così. `href="#"`, `href=""` e un `href` senza valore sono segnaposto, e falliscono come un link rotto. Il rapporto raggruppa per destinazione e nomina le pagine che la citano: un link rotto nel footer è un problema solo, non uno per pagina. Restano fuori, e il rapporto li conta, i link esterni, che chiederebbero la rete, `mailto:`, `tel:` e gli altri schemi, e l'id a cui punta un'ancora. Una `dist/client` senza HTML è un fallimento, perché il controllo non affermerebbe niente: un progetto che rende ogni pagina a richiesta lo spegne con `features.links: false`. Due limiti: con una `base` i link non si risolvono, e un redirect di `vercel.json` non è una pagina, quindi un link che ci porta passa per rotto, e si corregge puntando alla destinazione.
 
 `check secrets` legge le chiavi di `env.schema` con `context: 'server'` e `access: 'secret'`, dal sorgente di `astro.config.mjs` come `doctor`, e le cerca in ogni file di `dist/client`: un import sbagliato basta a portare un segreto nel browser. Per ogni chiave cerca il valore che ha nell'ambiente, anche nelle forme in cui Astro lo scrive nel markup e negli script, e il suo canary, `officina-<CHIAVE>-canary`, che `--canaries` stampa come righe `CHIAVE=valore` da mettere nell'ambiente della build. `actions/ci` lo fa dopo `pnpm run ci`, così i test che `ci` lancia non vedono i canary e la build sì. Il canary si dà solo ai campi `envField.string` senza validazioni (`max`, `min`, `length`, `url`, `includes`, `startsWith`, `endsWith`), perché Astro valida ogni variabile sul suo tipo e su quelle, e un canary che non le rispetta fermerebbe la build: una chiave così, in CI, resta da verificare. Una chiave che compare in un file è un fallimento che nomina la chiave e il file. Una chiave senza valore né canary nell'ambiente, o con un valore di meno di 8 caratteri, che cercato darebbe falsi positivi, non si verifica: il rapporto la dice con un avviso, invece di contarla fra le verificate. Uno schema senza chiavi segrete non ha niente da verificare, e una `dist/client` vuota è un fallimento.
@@ -66,7 +76,7 @@ Per Lighthouse un sito SSR si misura con `check lighthouse <url>`, sulla produzi
 
 Lo smoke legge gli header di sicurezza sulla pagina a cui arriva la radice. Se `/` è un redirect sulla stessa origine — il 302 di lingua che Astro emette con `i18n.routing.redirectToDefaultLocale`, per esempio — li cerca sulla destinazione, perché il redirect non porta la CSP delle pagine renderizzate, e il nome del controllo dice dove li ha letti: `header content-security-policy su /it`. Un redirect verso un'altra origine, o senza `location`, è un fallimento. Anche l'attesa che l'alias di produzione punti al deployment nuovo conta un 3xx come una risposta.
 
-Lo smoke visita anche le pagine rese a richiesta, quelle di `src/pages` con `export const prerender = false`. Ognuna risponde 200, oppure con un redirect sulla stessa origine, come una pagina protetta che rimanda all'accesso; un 200 è HTML e porta il meta `Content-Security-Policy` con la direttiva `script-src`, quello che il middleware dei template scrive nelle pagine rese a richiesta. Una pagina dinamica si visita col suo rappresentante di `routes.representatives`, altrimenti si salta dicendolo. Queste pagine non entrano nel controllo della barra finale né in Lighthouse. Nella 0.12.0 un'anomalia è un avviso, che lo smoke stampa con `·` senza fallire; dalla 0.13.0 sarà un fallimento. officina riconosce una pagina resa a richiesta dalla dichiarazione: con `output: 'server'`, una pagina senza `prerender = false` resta per tutti i gate una pagina prerenderizzata, e lo smoke la visita come le altre, senza cercarne la CSP.
+Lo smoke visita anche le pagine rese a richiesta, quelle di `src/pages` con `export const prerender = false`. Ognuna risponde 200, oppure con un redirect sulla stessa origine, come una pagina protetta che rimanda all'accesso; un 200 è HTML e porta il meta `Content-Security-Policy` con la direttiva `script-src`, quello che il middleware dei template scrive nelle pagine rese a richiesta. Una pagina dinamica si visita col suo rappresentante di `routes.representatives`, altrimenti si salta dicendolo. Queste pagine non entrano nel controllo della barra finale né in Lighthouse. Nella 0.12.0 e nella 0.13.0 un'anomalia è un avviso, che lo smoke stampa con `·` senza fallire; dalla 0.14.0 sarà un fallimento. officina riconosce una pagina resa a richiesta dalla dichiarazione: con `output: 'server'`, una pagina senza `prerender = false` resta per tutti i gate una pagina prerenderizzata, e lo smoke la visita come le altre, senza cercarne la CSP.
 
 Quando fallisce, lo smoke dice che la produzione è online e rotta, e consiglia di tornare indietro dalla dashboard di Vercel promuovendo l'ultimo deployment di produzione sano. Con `features.database` accesa aggiunge che lo schema non torna indietro: le migrazioni già applicate restano, e il deployment promosso regge solo se sono compatibili con il suo codice, la regola di «Migrazioni compatibili con la produzione» in § Action per i workflow.
 

package/dist/checks/bundle.js

@@ -5,7 +5,7 @@ import { join, relative } from 'node:path';
 import process from 'node:process';
 import { gzipSync } from 'node:zlib';
 import { budgetFor, CSS_BUDGET_GZIP, deferredClosure, htmlEntries, htmlStylesheets, parseEdges, staticClosure, } from '../lib/bundle-budget.js';
-import { measureCss, routeCount } from '../lib/bundle-css.js';
+import { inlineStyles, measureCss, rangeQueryFailures, routeCount } from '../lib/bundle-css.js';
 import { readSsr } from '../lib/bundle-ssr.js';
 import { missingInput } from '../lib/cli.js';
 import { loadConfig } from '../lib/config.js';
@@ -89,6 +89,17 @@ function checkCss(pages, cssMaxGzip, width) {
     printCss(css, cssMaxGzip, width);
     return css.failures;
 }
+function checkRangeSyntax() {
+    const sheets = filesWithExtension(ASSETS, '.css').map((file) => ({ file, css: readFileSync(file, 'utf8') }));
+    const pages = filesWithExtension(DIST, '.html').map((file) => ({
+        file,
+        css: inlineStyles(readFileSync(file, 'utf8')),
+    }));
+    const failures = rangeQueryFailures([...sheets, ...pages]);
+    if (failures.length === 0)
+        console.log('\nMedia query in sintassi di intervallo: nessuna.');
+    return failures;
+}
 function printSsrNote(expected, ssr) {
     for (const note of ssr.notes)
         console.log(`\nNOTA  ${note}`);
@@ -124,7 +135,7 @@ export async function main() {
     failures.push(...ssr.failures, ...unknownChunkFailures(pages), ...overBudgetFailures(pages));
     const width = Math.max('ROTTA'.length, ...pages.map((p) => p.route.length));
     printPages(pages, width);
-    failures.push(...checkCss(routes, cssMaxGzip, width));
+    failures.push(...checkCss(routes, cssMaxGzip, width), ...checkRangeSyntax());
     printSsrNote(expected, ssr);
     printDisabled(expected);
     if (failures.length > 0) {

package/dist/checks/smoke.js

@@ -70,9 +70,9 @@ export async function main(args = []) {
         return 1;
     }
     const warnings = results.filter(({ status }) => status === 'warn').length;
-    // TODO: dalla 0.13.0 le anomalie a richiesta sono `fail` (smoke-on-demand.ts): togli il log degli avvisi qui sotto.
+    // TODO: dalla 0.14.0 le anomalie a richiesta sono `fail` (smoke-on-demand.ts): togli il log degli avvisi qui sotto.
     if (warnings > 0)
-        console.log(`\n· ${warnings} avviso/i: dalla 0.13.0 fanno fallire lo smoke.`);
+        console.log(`\n· ${warnings} avviso/i: dalla 0.14.0 fanno fallire lo smoke.`);
     console.log(`\n✓ Tutti i controlli passati su ${baseUrl}.\n`);
     return 0;
 }

package/dist/lib/alignment.js

@@ -28,7 +28,7 @@ export const CI_STEPS = [
     'doctor',
 ];
 const MANIFEST = 'package.json';
-// TODO: dalla 0.13.0 `check:secrets` è un errore di doctor: toglilo da NEW_SCRIPTS.
+// TODO: dalla 0.14.0 `check:secrets` è un errore di doctor: toglilo da NEW_SCRIPTS.
 const NEW_SCRIPTS = new Set(['check:secrets']);
 export function scriptGaps({ scripts = {} }) {
     const gaps = [];

package/dist/lib/bundle-css.d.ts

@@ -12,5 +12,12 @@ export type CssMeasure = {
     groups: CssGroup[];
     failures: string[];
 };
+export type CssSource = {
+    file: string;
+    css: string;
+};
 export declare const routeCount: (count: number) => string;
 export declare function measureCss(routes: readonly RouteStylesheets[], sheets: readonly Stylesheet[], maxGzip: number, assets: string): CssMeasure;
+export declare function rangeMediaQueries(css: string): string[];
+export declare const inlineStyles: (html: string) => string;
+export declare function rangeQueryFailures(sources: readonly CssSource[]): string[];

package/dist/lib/bundle-css.js

@@ -1,3 +1,7 @@
+const CSS_COMMENT = /\/\*[\s\S]*?\*\//g;
+const MEDIA_PRELUDE = /(?<=@media\b)[^{;]*/gi;
+const RANGE_COMPARISON = /[<>=]/;
+const STYLE_ELEMENT = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
 const kb = (bytes) => `${(bytes / 1024).toFixed(1)} KB`;
 export const routeCount = (count) => (count === 1 ? '1 rotta' : `${count} rotte`);
 function overBudget({ stylesheets, gzip, routes }, maxGzip) {
@@ -31,3 +35,18 @@ export function measureCss(routes, sheets, maxGzip, assets) {
     failures.push(...measured.filter((group) => group.gzip > maxGzip).map((group) => overBudget(group, maxGzip)));
     return { groups: measured, failures };
 }
+export function rangeMediaQueries(css) {
+    const preludes = [...css.replace(CSS_COMMENT, ' ').matchAll(MEDIA_PRELUDE)].map(([prelude]) => prelude.trim());
+    return [...new Set(preludes.filter((prelude) => RANGE_COMPARISON.test(prelude)))];
+}
+export const inlineStyles = (html) => [...html.matchAll(STYLE_ELEMENT)].map(([, css]) => css).join('\n');
+export function rangeQueryFailures(sources) {
+    return sources.flatMap(({ file, css }) => {
+        const queries = rangeMediaQueries(css);
+        if (queries.length === 0)
+            return [];
+        return [
+            `${file}: media query in sintassi di intervallo, che Safari legge solo dalla 16.4 — ${queries.join(', ')}; si abbassano con \`vite.build.cssTarget\``,
+        ];
+    });
+}

package/dist/lib/database-auth.js

@@ -72,7 +72,7 @@ function secretGaps(source, keys) {
         return message === undefined ? [] : [{ path: ASTRO_CONFIG, message }];
     });
 }
-// TODO: dalla 0.13.0 i requisiti del database e dell'autenticazione sono errori di doctor: togli `severity`.
+// TODO: dalla 0.14.0 i requisiti del database e dell'autenticazione sono errori di doctor: togli `severity`.
 const asWarning = (gap) => ({ ...gap, severity: 'warning' });
 export function databaseAuthGaps(files, manifest, on) {
     const database = on.includes('database') ? databaseGaps(files, manifest) : [];

package/dist/lib/smoke-on-demand.js

@@ -18,7 +18,7 @@ const attributeValue = (tag, attribute) => {
 };
 const hasCspMeta = (html) => [...html.matchAll(META)].some(([tag]) => attributeValue(tag, HTTP_EQUIV).toLowerCase() === 'content-security-policy' &&
     SCRIPT_SRC.test(attributeValue(tag, CONTENT)));
-// TODO: dalla 0.13.0 un'anomalia di una pagina resa a richiesta fa fallire lo smoke: qui `warn` diventa `fail`.
+// TODO: dalla 0.14.0 un'anomalia di una pagina resa a richiesta fa fallire lo smoke: qui `warn` diventa `fail`.
 const warn = (check, detail) => ({ check, status: 'warn', detail });
 function redirect(check, response, url) {
     const location = response.headers.get('location');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elia97/officina",
-  "version": "0.12.0",
+  "version": "0.13.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",