@elia97/officina 0.4.0 → 0.5.0

package/dist/gen/section-targets.d.mts

@@ -19,5 +19,10 @@ export declare function sectionTargets({ camel, kebab, pascal }: {
     sectionsMarker: string;
 };
 export declare const sectionFiles: (targets: any, kebab: any) => string[];
+export declare function sectionedCollections(root: any): {
+    camel: string;
+    kebab: string;
+    pascal: string;
+}[];
 export declare function findSectionedPages(root: any, marker: any): string[];
 export declare function validateSectionName(plop: any): (value: any) => string | true;

package/dist/gen/section-targets.mjs

@@ -1,6 +1,10 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
+import { Project } from 'ts-morph';
 import { isValidIdentifier } from './identifier.mjs';
+const CONFIG_PATH = 'src/content.config.ts';
+const SCHEMAS = /^@\/lib\/schemas\/(.+)$/;
+const COLLECTION_SCHEMA = 'CollectionSchema';
 export function casings(plop, value) {
     return {
         camel: plop.getHelper('camelCase')(value),
@@ -26,6 +30,25 @@ export const sectionFiles = (targets, kebab) => [
     `${targets.contentDir}/${kebab}.yml`,
     `${targets.componentDir}/${kebab}.astro`,
 ];
+// Le collection a sezioni si riconoscono dall'import che `gen:collection` scrive in
+// content.config.ts, non dai marcatori nelle pagine: quelli sono proprio ciò che può sparire.
+export function sectionedCollections(root) {
+    const config = new Project().addSourceFileAtPath(join(root, CONFIG_PATH));
+    return config.getImportDeclarations().flatMap((declaration) => {
+        const kebab = SCHEMAS.exec(declaration.getModuleSpecifierValue())?.[1];
+        if (kebab === undefined)
+            return [];
+        return declaration.getNamedImports().flatMap((named) => {
+            const name = named.getName();
+            if (!name.endsWith(COLLECTION_SCHEMA))
+                return [];
+            const camel = name.slice(0, -COLLECTION_SCHEMA.length);
+            if (camel === '')
+                return [];
+            return [{ camel, kebab, pascal: `${camel[0].toUpperCase()}${camel.slice(1)}` }];
+        });
+    });
+}
 export function findSectionedPages(root, marker) {
     return readdirSync(join(root, 'src/pages'), { recursive: true, withFileTypes: true })
         .filter((entry) => entry.isFile() && entry.name.endsWith('.astro'))

package/dist/icons.d.ts

@@ -0,0 +1 @@
+export { ICON_SPECS } from './lib/icon-specs.ts';

package/dist/icons.js

@@ -0,0 +1,2 @@
+// Il test che confronta le icone col manifest del sito importa questo, senza caricare sharp.
+export { ICON_SPECS } from './lib/icon-specs.js';

package/dist/index.d.ts

@@ -1,10 +1,6 @@
 export type { Budget } from './lib/bundle-budget.ts';
-export { CSS_BUDGET_GZIP } from './lib/bundle-budget.ts';
 export type { OfficinaConfig } from './lib/config.ts';
 export { defineConfig } from './lib/config.ts';
 export type { IconSpec } from './lib/icon-specs.ts';
-export { ICON_SPECS } from './lib/icon-specs.ts';
 export type { VerifiedRoute } from './lib/routes.ts';
-export { NON_HTML_ROUTES } from './lib/routes.ts';
 export type { CheckResult, SmokeCheck, SmokeContext } from './lib/smoke-production.ts';
-export { checkBotIdChallenge, checkCanonicalHost, checkPages, checkSecurityHeaders, checkTrailingSlash, DEFAULT_CHECKS, SECURITY_HEADERS, } from './lib/smoke-production.ts';

package/dist/index.js

@@ -1,5 +1 @@
-export { CSS_BUDGET_GZIP } from './lib/bundle-budget.js';
 export { defineConfig } from './lib/config.js';
-export { ICON_SPECS } from './lib/icon-specs.js';
-export { NON_HTML_ROUTES } from './lib/routes.js';
-export { checkBotIdChallenge, checkCanonicalHost, checkPages, checkSecurityHeaders, checkTrailingSlash, DEFAULT_CHECKS, SECURITY_HEADERS, } from './lib/smoke-production.js';

package/dist/lib/alignment.d.ts

@@ -1,4 +1,3 @@
-import type { OfficinaConfig } from './config.ts';
 import type { ContractGap } from './contract.ts';
 export interface ProjectFiles {
     /** Tracciati e non tracciati, senza gli ignorati: un file locale fuori da git non è un residuo. */
@@ -14,10 +13,7 @@ export declare const EXPECTED_SCRIPTS: Readonly<Record<string, string>>;
 export declare const CI_STEPS: readonly string[];
 export declare function scriptGaps({ scripts }: Manifest): ContractGap[];
 export declare function dependencyGaps({ dependencies, devDependencies }: Manifest): ContractGap[];
-export declare function leftoverGaps({ paths, read }: ProjectFiles): ContractGap[];
+export declare function leftoverGaps(files: ProjectFiles): ContractGap[];
 export declare const BIOME_PRESET = "@elia97/officina/biome";
 export declare const LEFTHOOK_PRESET = "node_modules/@elia97/officina/presets/lefthook.yml";
-export declare function presetGaps({ read }: ProjectFiles): ContractGap[];
-export declare function workflowGaps({ read }: ProjectFiles): ContractGap[];
-/** `loaded` è la configurazione letta, l'errore che il suo caricamento ha sollevato, o `undefined` se il file non c'è. */
-export declare function configGaps(loaded: OfficinaConfig | Error | undefined): ContractGap[];
+export declare function presetGaps(files: ProjectFiles): ContractGap[];

package/dist/lib/alignment.js

@@ -1,3 +1,4 @@
+import { mentions } from './workflows.js';
 export const EXPECTED_SCRIPTS = {
     'check:comments': 'officina check comments',
     'check:language': 'officina check language',
@@ -94,73 +95,45 @@ const LEFTOVERS = [
     { path: 'docs/ESTIMATE.md', reason: OUT_OF_REPOSITORY },
 ];
 const holds = (paths, target) => target.endsWith('/') ? paths.some((path) => path.startsWith(target)) : paths.includes(target);
-export function leftoverGaps({ paths, read }) {
-    const gaps = LEFTOVERS.filter(({ path }) => holds(paths, path)).map(({ path, reason }) => ({
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// I file JSON si leggono come JSON: `"hooks"` dentro un valore qualunque non è un blocco `hooks`,
+// e un file illeggibile non è un file che dichiara quello che si cerca.
+function readJson({ read }, path) {
+    const source = read(path);
+    if (source === undefined)
+        return undefined;
+    try {
+        const value = JSON.parse(source);
+        return isRecord(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function leftoverGaps(files) {
+    const gaps = LEFTOVERS.filter(({ path }) => holds(files.paths, path)).map(({ path, reason }) => ({
         path,
         message: `residuo: ${reason}`,
     }));
-    if (read('.claude/settings.json')?.includes('"hooks"')) {
+    if (readJson(files, '.claude/settings.json')?.hooks !== undefined) {
         gaps.push({ path: '.claude/settings.json', message: `blocco \`hooks\` residuo: il guard ${FROM_PLUGIN}` });
     }
-    if (read('.mcp.json')?.includes('astro-docs')) {
+    const servers = readJson(files, '.mcp.json')?.mcpServers;
+    if (isRecord(servers) && servers['astro-docs'] !== undefined) {
         gaps.push({ path: '.mcp.json', message: `server \`astro-docs\` residuo: ${FROM_PLUGIN}` });
     }
     return gaps;
 }
 export const BIOME_PRESET = '@elia97/officina/biome';
 export const LEFTHOOK_PRESET = 'node_modules/@elia97/officina/presets/lefthook.yml';
-export function presetGaps({ read }) {
+export function presetGaps(files) {
     const gaps = [];
-    if (!read('biome.json')?.includes(BIOME_PRESET)) {
+    const extended = readJson(files, 'biome.json')?.extends;
+    if (!(Array.isArray(extended) && extended.includes(BIOME_PRESET))) {
         gaps.push({ path: 'biome.json', message: `non estende \`${BIOME_PRESET}\`` });
     }
-    if (!read('lefthook.yml')?.includes(LEFTHOOK_PRESET)) {
+    if (!mentions(files.read('lefthook.yml'), LEFTHOOK_PRESET)) {
         gaps.push({ path: 'lefthook.yml', message: `non estende \`${LEFTHOOK_PRESET}\`` });
     }
     return gaps;
 }
-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 PINNED_REF = /^(v\d+\.\d+\.\d+|[0-9a-f]{40})$/;
-function actionGap(source, action) {
-    const name = `Elia97/officina/actions/${action}`;
-    if (source === undefined)
-        return `manca: i suoi passi arrivano da \`${name}\``;
-    const ref = new RegExp(`${name}@(\\S+)`).exec(source)?.[1];
-    if (ref === undefined)
-        return `non usa \`${name}\``;
-    return PINNED_REF.test(ref)
-        ? undefined
-        : `\`${name}@${ref}\`: il riferimento va fissato a un tag di versione o a uno SHA`;
-}
-export function workflowGaps({ read }) {
-    return ACTIONS.flatMap(({ workflow, action }) => {
-        const message = actionGap(read(workflow), action);
-        return message === undefined ? [] : [{ path: workflow, message }];
-    });
-}
-const CONFIG = 'officina.config.ts';
-function siteUrlGap(siteUrl) {
-    if (siteUrl === undefined)
-        return '`siteUrl` assente: `check smoke` non ha un host canonico';
-    if (!URL.canParse(siteUrl))
-        return `\`siteUrl\` non è un URL: \`${siteUrl}\``;
-    return siteUrl.endsWith('/') ? `\`siteUrl\` finisce con una barra: \`${siteUrl}\`` : undefined;
-}
-/** `loaded` è la configurazione letta, l'errore che il suo caricamento ha sollevato, o `undefined` se il file non c'è. */
-export function configGaps(loaded) {
-    if (loaded === undefined)
-        return [{ path: CONFIG, message: 'manca: i valori del progetto per officina stanno qui' }];
-    if (loaded instanceof Error)
-        return [{ path: CONFIG, message: `non si carica: ${loaded.message}` }];
-    const messages = [
-        siteUrlGap(loaded.siteUrl),
-        loaded.icons === undefined ? '`icons.background` assente: `gen icons` non ha un colore di fondo' : undefined,
-    ];
-    return messages.filter((message) => message !== undefined).map((message) => ({ path: CONFIG, message }));
-}

package/dist/lib/anchors.d.ts

@@ -0,0 +1,2 @@
+import type { ContractGap } from './contract.ts';
+export declare function anchorGaps(root: string): ContractGap[];

package/dist/lib/anchors.js

@@ -0,0 +1,35 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { HookPointError } from '../gen/hook-points.mjs';
+import { assertSectionAnchors } from '../gen/inject-section.mjs';
+import { assertDictionaries } from '../gen/inject-strings.mjs';
+import { sectionedCollections } from '../gen/section-targets.mjs';
+// Gli ancoraggi che i generatori trovano al lancio, guardati senza generare niente: sono gli
+// stessi controlli del pre-volo, tolto ciò che dipende dal nome della cosa nuova.
+const CONFIG = 'src/content.config.ts';
+const DICTIONARIES = 'src/i18n/strings';
+function gapsFrom(fallback, check) {
+    try {
+        check();
+        return [];
+    }
+    catch (error) {
+        if (error instanceof HookPointError)
+            return [{ path: String(error.path), message: String(error.problem) }];
+        return [{ path: fallback, message: `non si lascia leggere: ${String(error)}` }];
+    }
+}
+function sectionGaps(root) {
+    if (!existsSync(join(root, CONFIG)))
+        return [];
+    const collections = sectionedCollections(root);
+    return collections.flatMap((collection) => gapsFrom(CONFIG, () => assertSectionAnchors({ root, collection })));
+}
+function dictionaryGaps(root) {
+    if (!existsSync(join(root, DICTIONARIES)))
+        return [];
+    return gapsFrom(DICTIONARIES, () => assertDictionaries({ root }));
+}
+export function anchorGaps(root) {
+    return [...sectionGaps(root), ...dictionaryGaps(root)];
+}

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

@@ -13,7 +13,12 @@ export declare function budgetFor(route: string, budgets?: readonly Budget[]): B
 /** Rollup racchiude gli specificatori statici con `"` e i dinamici in un template literal. */
 export declare function parseEdges(source: string): Pick<Chunk, 'static' | 'dynamic'>;
 export declare function htmlEntries(html: string): string[];
-export declare function staticClosure(entries: Iterable<string>, chunks: Map<string, Chunk>): Set<string>;
+/** `unknown`: i nomi citati che in `dist/client/_astro` non ci sono — saltarli vorrebbe dire misurare meno del vero. */
+export type Closure = {
+    reached: Set<string>;
+    unknown: Set<string>;
+};
+export declare function staticClosure(entries: Iterable<string>, chunks: Map<string, Chunk>): Closure;
 export declare function deferredClosure(reached: Set<string>, chunks: Map<string, Chunk>): Set<string>;
 export declare const CSS_BUDGET_GZIP: number;
 export type Stylesheet = {

package/dist/lib/bundle-budget.js

@@ -17,23 +17,26 @@ export function htmlEntries(html) {
     return [...captured(html, /(?:src|href)="\/_astro\/([^"]+\.js)"/g, 1)];
 }
 export function staticClosure(entries, chunks) {
-    const seen = new Set();
+    const reached = new Set();
+    const unknown = new Set();
     const queue = [...entries];
     while (queue.length > 0) {
         const name = queue.pop();
-        if (name === undefined || seen.has(name))
+        if (name === undefined || reached.has(name))
             continue;
         const chunk = chunks.get(name);
-        if (chunk === undefined)
+        if (chunk === undefined) {
+            unknown.add(name);
             continue;
-        seen.add(name);
+        }
+        reached.add(name);
         queue.push(...chunk.static);
     }
-    return seen;
+    return { reached, unknown };
 }
 export function deferredClosure(reached, chunks) {
     const entries = [...reached].flatMap((name) => [...(chunks.get(name)?.dynamic ?? [])]);
-    return new Set([...staticClosure(entries, chunks)].filter((name) => !reached.has(name)));
+    return new Set([...staticClosure(entries, chunks).reached].filter((name) => !reached.has(name)));
 }
 export const CSS_BUDGET_GZIP = 12 * 1024;
 export function heaviestStylesheet(sheets) {

package/dist/lib/config-gaps.d.ts

@@ -0,0 +1,7 @@
+import { type OfficinaConfig } from './config.ts';
+import type { ContractGap } from './contract.ts';
+/**
+ * `loaded` è la configurazione letta, l'errore che il suo caricamento ha sollevato, o `undefined` se
+ * il file non c'è; `patterns` i pattern dinamici di `src/pages` rimasti senza rappresentante.
+ */
+export declare function configGaps(loaded: OfficinaConfig | Error | undefined, patterns?: readonly string[]): ContractGap[];

package/dist/lib/config-gaps.js

@@ -0,0 +1,29 @@
+import { FEATURES } from './config.js';
+const CONFIG = 'officina.config.ts';
+function siteUrlGap(siteUrl) {
+    if (siteUrl === undefined)
+        return '`siteUrl` assente: `check smoke` non ha un host canonico';
+    if (!URL.canParse(siteUrl))
+        return `\`siteUrl\` non è un URL: \`${siteUrl}\``;
+    return siteUrl.endsWith('/') ? `\`siteUrl\` finisce con una barra: \`${siteUrl}\`` : undefined;
+}
+// Il silenzio vale `'required'`: un controllo si spegne dichiarandolo, non dimenticandolo.
+const featureGaps = (config) => FEATURES.filter((name) => config.features?.[name] === undefined).map((name) => `\`features.${name}\` non dichiarata: vale \`'required'\`, e il gate fallisce se non trova cosa controllare`);
+const representativeGaps = (patterns) => patterns.map((label) => `\`routes.representatives\` non ha un percorso per \`${label}\`: smoke e Lighthouse non guardano quella pagina`);
+/**
+ * `loaded` è la configurazione letta, l'errore che il suo caricamento ha sollevato, o `undefined` se
+ * il file non c'è; `patterns` i pattern dinamici di `src/pages` rimasti senza rappresentante.
+ */
+export function configGaps(loaded, patterns = []) {
+    if (loaded === undefined)
+        return [{ path: CONFIG, message: 'manca: i valori del progetto per officina stanno qui' }];
+    if (loaded instanceof Error)
+        return [{ path: CONFIG, message: `non si carica: ${loaded.message}` }];
+    const messages = [
+        siteUrlGap(loaded.siteUrl),
+        loaded.icons === undefined ? '`icons.background` assente: `gen icons` non ha un colore di fondo' : undefined,
+        ...featureGaps(loaded),
+        ...representativeGaps(patterns),
+    ];
+    return messages.filter((message) => message !== undefined).map((message) => ({ path: CONFIG, message }));
+}

package/dist/lib/config.d.ts

@@ -1,6 +1,8 @@
 import type { Budget } from './bundle-budget.ts';
-import type { VerifiedRoute } from './routes.ts';
+import type { Representatives, VerifiedRoute } from './routes.ts';
 import type { SmokeCheck } from './smoke-production.ts';
+/** `'required'` fa fallire il gate quando ciò che deve controllare non c'è; `false` lo spegne. */
+export type FeatureSetting = 'required' | false;
 export interface OfficinaConfig {
     /** L'apice di produzione, senza barra finale: lo usa `check smoke` quando non riceve un URL. */
     siteUrl?: string;
@@ -19,7 +21,20 @@ export interface OfficinaConfig {
     analytics?: {
         linkTracking?: string;
     };
+    /** Quali controlli il progetto pretende. Una voce non dichiarata vale `'required'`. */
+    features?: {
+        analytics?: FeatureSetting;
+        roadmap?: FeatureSetting;
+    };
+    /** Per ogni pattern dinamico di `src/pages`, un percorso vero che smoke e Lighthouse visitano. */
+    routes?: {
+        representatives?: Representatives;
+    };
 }
+export declare const FEATURES: readonly ['analytics', 'roadmap'];
+export type FeatureName = (typeof FEATURES)[number];
+/** Un controllo si spegne solo scrivendolo: il silenzio vale `'required'`. */
+export declare const isRequired: (config: OfficinaConfig, name: FeatureName) => boolean;
 export declare const defineConfig: (config: OfficinaConfig) => OfficinaConfig;
 export declare const findConfigFile: (root: string) => string | undefined;
 export declare function loadConfig(root: string): Promise<OfficinaConfig>;

package/dist/lib/config.js

@@ -7,16 +7,48 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { aFunction, aNumber, anArrayOf, aRecordOf, aShape, aString, aStringOrNull, oneOf } from './validate.js';
+export const FEATURES = ['analytics', 'roadmap'];
+/** Un controllo si spegne solo scrivendolo: il silenzio vale `'required'`. */
+export const isRequired = (config, name) => (config.features?.[name] ?? 'required') === 'required';
+const budget = aShape({ label: aString, matches: aFunction, maxGzip: aNumber });
+const verifiedRoute = aShape({ path: aString, type: aString });
+const feature = oneOf("'required' oppure false", ['required', false]);
+const SHAPE = aShape({
+    siteUrl: aString,
+    icons: aShape({ background: aString }),
+    bundle: aShape({ budgets: anArrayOf(budget), cssMaxGzip: aNumber }),
+    smoke: aShape({
+        securityHeaders: aRecordOf(aStringOrNull),
+        nonHtmlRoutes: anArrayOf(verifiedRoute),
+        checks: anArrayOf(aFunction),
+    }),
+    analytics: aShape({ linkTracking: aString }),
+    features: aShape({ analytics: feature, roadmap: feature }),
+    routes: aShape({ representatives: aRecordOf(aString) }),
+});
 const CONFIG_FILES = ['officina.config.ts', 'officina.config.mjs', 'officina.config.js'];
 export const defineConfig = (config) => config;
 // Fuori da node_modules Node toglie i tipi da solo: il file del progetto può essere TypeScript.
-export const findConfigFile = (root) => CONFIG_FILES.map((name) => join(root, name)).find((path) => existsSync(path));
+const findConfigFiles = (root) => CONFIG_FILES.map((name) => join(root, name)).filter((path) => existsSync(path));
+export const findConfigFile = (root) => findConfigFiles(root)[0];
 export async function loadConfig(root) {
-    const file = findConfigFile(root);
+    const [file, ...rest] = findConfigFiles(root);
     if (file === undefined)
         return {};
+    if (rest.length > 0) {
+        const names = [file, ...rest].map((path) => basename(path)).join(' e ');
+        throw new Error(`${names} stanno insieme nella radice: quale valga non lo decide officina, tienine uno`);
+    }
+    const name = basename(file);
     const module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
-    return module.default ?? {};
+    if (module.default === undefined) {
+        throw new Error(`${name} non ha un default export: la configurazione si scrive \`export default defineConfig({ … })\``);
+    }
+    const problems = SHAPE(module.default, '');
+    if (problems.length > 0)
+        throw new Error(problems.join('; '));
+    return module.default;
 }

package/dist/lib/contract.d.ts

@@ -12,6 +12,14 @@ type Requirement = {
     path: string;
     text: string;
     reason: string;
+} | {
+    kind: 'dependency';
+    name: string;
+    reason: string;
+} | {
+    kind: 'script';
+    name: string;
+    reason: string;
 };
 export declare const CONTRACT: Requirement[];
 export interface ContractGap {

package/dist/lib/contract.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+const MANIFEST = 'package.json';
 export const CONTRACT = [
     { kind: 'file', path: 'src/components/ui/section.astro', reason: 'le sezioni generate la importano' },
     { kind: 'file', path: 'src/components/ui/container.astro', reason: 'le sezioni e le pagine generate lo importano' },
@@ -27,33 +28,77 @@ export const CONTRACT = [
         extension: '.ts',
         reason: 'gen:collection e gen:section scrivono lì gli schemi',
     },
+    {
+        kind: 'anchor',
+        path: 'src/lib/schemas/common.ts',
+        text: 'export const ctaSchema',
+        reason: 'lo schema di ogni sezione generata lo importa da ../common',
+    },
+    {
+        kind: 'anchor',
+        path: 'src/lib/schemas/common.ts',
+        text: 'export function imageSchema',
+        reason: "lo schema di una sezione con immagine lo importa da ../common, e lo chiama con l'helper di Astro",
+    },
+    {
+        kind: 'file',
+        path: 'src/assets/placeholder.jpg',
+        reason: 'il contenuto di una sezione con immagine ci punta appena generato',
+    },
     {
         kind: 'anchor',
         path: 'src/content.config.ts',
         text: 'export const collections',
         reason: 'gen:collection e gen:section registrano lì la collection',
     },
+    {
+        kind: 'dependency',
+        name: 'class-variance-authority',
+        reason: 'il componente che scrive gen:component lo importa',
+    },
+    { kind: 'script', name: 'check', reason: 'il post-gen di ogni generatore lo lancia con `pnpm run check`' },
 ];
 function hasFileWith(directory, extension) {
     if (!existsSync(directory) || !statSync(directory).isDirectory())
         return false;
     return readdirSync(directory, { recursive: true }).some((entry) => String(entry).endsWith(extension));
 }
-function gapFor(root, requirement) {
+function manifestGap(manifest, requirement) {
+    if (requirement.kind === 'script') {
+        return manifest.scripts?.[requirement.name] === undefined
+            ? { path: MANIFEST, message: `manca lo script \`${requirement.name}\`: ${requirement.reason}` }
+            : undefined;
+    }
+    if (requirement.kind !== 'dependency')
+        return undefined;
+    const declared = { ...manifest.dependencies, ...manifest.devDependencies };
+    return declared[requirement.name] === undefined
+        ? { path: MANIFEST, message: `manca la dipendenza \`${requirement.name}\`: ${requirement.reason}` }
+        : undefined;
+}
+function pathGap(root, requirement) {
+    if (requirement.kind === 'dependency' || requirement.kind === 'script')
+        return undefined;
+    const gap = (message) => ({ path: requirement.path, message });
     const target = join(root, requirement.path);
     if (requirement.kind === 'directory') {
-        return hasFileWith(target, requirement.extension) ? undefined : `manca, o è vuota: ${requirement.reason}`;
+        return hasFileWith(target, requirement.extension) ? undefined : gap(`manca, o è vuota: ${requirement.reason}`);
     }
     if (!existsSync(target))
-        return `manca: ${requirement.reason}`;
+        return gap(`manca: ${requirement.reason}`);
     if (requirement.kind === 'anchor' && !readFileSync(target, 'utf8').includes(requirement.text)) {
-        return `manca l'ancoraggio \`${requirement.text}\`: ${requirement.reason}`;
+        return gap(`manca l'ancoraggio \`${requirement.text}\`: ${requirement.reason}`);
     }
     return undefined;
 }
+function readManifest(root) {
+    const target = join(root, MANIFEST);
+    return existsSync(target) ? JSON.parse(readFileSync(target, 'utf8')) : {};
+}
 export function contractGaps(root) {
+    const manifest = readManifest(root);
     return CONTRACT.flatMap((requirement) => {
-        const message = gapFor(root, requirement);
-        return message === undefined ? [] : [{ path: requirement.path, message }];
+        const gap = pathGap(root, requirement) ?? manifestGap(manifest, requirement);
+        return gap === undefined ? [] : [gap];
     });
 }

package/dist/lib/pins.d.ts

@@ -0,0 +1,10 @@
+import { type Hit } from './cli.ts';
+/** Un file che porta il pin di un pacchetto scaricato al volo, e il suo contenuto. */
+export interface PinSite {
+    path: string;
+    source: string;
+}
+export interface PinHit extends Hit {
+    path: string;
+}
+export declare function pinFindings(pkg: string, latest: string, sites: readonly [PinSite, ...PinSite[]]): PinHit[];

package/dist/lib/pins.js

@@ -0,0 +1,48 @@
+import { readLines } from './cli.js';
+const EXACT = /^\d+\.\d+\.\d+$/;
+const escaped = (name) => name.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+function pinsOf(pkg, sites) {
+    const pattern = new RegExp(`(?<![\\w@/.-])${escaped(pkg)}@([\\w.-]+)`);
+    return sites.flatMap(({ path, source }) => readLines(source).flatMap(({ n, text }) => {
+        const version = pattern.exec(text)?.[1];
+        return version === undefined ? [] : [{ path, line: n, version }];
+    }));
+}
+const major = (version) => Number(/^(\d+)\./.exec(version)?.[1]);
+// Il pin esatto è il contratto: `vercel@59` ridà una CLI diversa ogni settimana, e un deploy che
+// fallisce non si riproduce. La major più nuova su npm resta una segnalazione, non un obbligo.
+export function pinFindings(pkg, latest, sites) {
+    const pins = pinsOf(pkg, sites);
+    const home = sites[0].path;
+    if (pins.length === 0) {
+        return [{ path: home, line: 1, message: `nessun \`${pkg}@<x.y.z>\`: il pin è sparito` }];
+    }
+    const loose = pins.filter(({ version }) => !EXACT.test(version));
+    if (loose.length > 0) {
+        return loose.map(({ path, line, version }) => ({
+            path,
+            line,
+            message: `${pkg}@${version}: il pin va scritto per intero, \`x.y.z\``,
+        }));
+    }
+    const versions = [...new Set(pins.map(({ version }) => version))].sort();
+    const [pinned = ''] = versions;
+    if (versions.length > 1) {
+        return pins.map(({ path, line, version }) => ({
+            path,
+            line,
+            message: `${pkg}@${version}: il pin non è lo stesso ovunque (${versions.join(', ')})`,
+        }));
+    }
+    const published = major(latest);
+    if (Number.isNaN(published)) {
+        return [{ path: home, line: 1, message: `versione pubblicata illeggibile: ${JSON.stringify(latest)}` }];
+    }
+    if (major(pinned) >= published)
+        return [];
+    return pins.map(({ path, line }) => ({
+        path,
+        line,
+        message: `${pkg}@${pinned}: su npm è pubblicata la major ${published}`,
+    }));
+}

package/dist/lib/routes.d.ts

@@ -18,6 +18,8 @@ export type VerifiedRoute = {
     path: string;
     type: string;
 };
+/** `/blog/[slug]` → `/blog/hello-world`: il percorso vero che sta per il pattern. */
+export type Representatives = Readonly<Record<string, string>>;
 export declare const ERROR_PAGES: readonly string[];
 export declare const NON_HTML_ROUTES: readonly VerifiedRoute[];
 export declare function filesWithExtension(dir: string, extension: string): string[];
@@ -26,6 +28,8 @@ export declare function routeOf(htmlPath: string, dist: string): string;
 export declare function expectedRoutes(pages: readonly PageFile[], pagesDir: string): Expectations;
 /** [HARD] Guardia fail-open: ogni asserzione per rotta itera sulle pagine emesse, quindi una dist vuota non asserisce niente. */
 export declare function missingRouteFailures(expected: Expectations, emitted: readonly string[], dist: string): string[];
-export declare function auditRoutes(expected: Expectations): string[];
-export declare function smokeRoutes(expected: Expectations, nonHtmlRoutes?: readonly VerifiedRoute[]): VerifiedRoute[];
+/** I pattern dinamici che `officina.config.ts` non ha ancora mandato nessuno a visitare. */
+export declare function missingRepresentatives(expected: Expectations, representatives?: Representatives): string[];
+export declare function auditRoutes(expected: Expectations, representatives?: Representatives): string[];
+export declare function smokeRoutes(expected: Expectations, nonHtmlRoutes?: readonly VerifiedRoute[], representatives?: Representatives): VerifiedRoute[];
 export declare function orphanExceptions(expected: Expectations): string[];

package/dist/lib/routes.js

@@ -81,15 +81,24 @@ export function missingRouteFailures(expected, emitted, dist) {
     }
     return failures;
 }
-// Ordinate: l'ordine nativo di readdirSync cambia da un filesystem all'altro.
-export function auditRoutes(expected) {
-    return expected.exact
-        .map(({ route }) => route)
-        .filter((route) => !ERROR_PAGES.includes(route))
+/** I pattern dinamici che `officina.config.ts` non ha ancora mandato nessuno a visitare. */
+export function missingRepresentatives(expected, representatives = {}) {
+    return expected.patterns
+        .map(({ label }) => label)
+        .filter((label) => representatives[label] === undefined)
         .sort();
 }
-export function smokeRoutes(expected, nonHtmlRoutes = NON_HTML_ROUTES) {
-    return [...auditRoutes(expected).map((path) => ({ path, type: 'text/html' })), ...nonHtmlRoutes];
+// Ordinate: l'ordine nativo di readdirSync cambia da un filesystem all'altro. Un pattern dinamico
+// entra col percorso vero che il progetto gli ha dato: senza, resta una pagina che nessuno guarda.
+export function auditRoutes(expected, representatives = {}) {
+    const exact = expected.exact.map(({ route }) => route).filter((route) => !ERROR_PAGES.includes(route));
+    const stand = expected.patterns
+        .map(({ label }) => representatives[label])
+        .filter((path) => path !== undefined);
+    return [...exact, ...stand].sort();
+}
+export function smokeRoutes(expected, nonHtmlRoutes = NON_HTML_ROUTES, representatives = {}) {
+    return [...auditRoutes(expected, representatives).map((path) => ({ path, type: 'text/html' })), ...nonHtmlRoutes];
 }
 export function orphanExceptions(expected) {
     const routes = new Set(expected.exact.map(({ route }) => route));

package/dist/lib/tooling.d.ts

@@ -0,0 +1,3 @@
+import type { Manifest } from './alignment.ts';
+import type { ContractGap } from './contract.ts';
+export declare function toolingGaps({ devDependencies }: Manifest): ContractGap[];