@elia97/officina 0.3.0 → 0.5.0

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

@@ -1,7 +1,30 @@
-export declare function assertSectionInjectable({ root, collection, camel, kebab, pascal, image }: {
+import { Project } from 'ts-morph';
+export declare function assertSectionAnchors({ root, collection, project }: {
+    collection: any;
+    project?: Project | undefined;
+    root: any;
+}): {
+    targets: {
+        barrel: string;
+        schemaFunction: string;
+        dataLayer: string;
+        dataFunction: string;
+        schemaDir: string;
+        contentDir: string;
+        componentDir: string;
+        importsMarker: string;
+        sectionsMarker: string;
+    };
+    barrel: any;
+    fn: any;
+    union: any;
+    obj: any;
+    page: string | undefined;
+    src: string;
+};
+export declare function assertSectionInjectable({ root, collection, camel, kebab, pascal }: {
     camel: any;
     collection: any;
-    image?: boolean | undefined;
     kebab: any;
     pascal: any;
     root: any;

package/dist/gen/inject-section.mjs

@@ -2,12 +2,11 @@
 // trivia iniziale del nuovo import e lo sposta nel blocco ordinato. (.astro non è leggibile da ts-morph.)
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { Node, Project, SyntaxKind } from 'ts-morph';
+import { failing } from './hook-points.mjs';
 import { findSectionedPages, sectionFiles, sectionTargets } from './section-targets.mjs';
 import { isNameTaken } from './ts-morph-utils.mjs';
 const GUIDE = 'docs/guides/content-collections.md';
-function fail(where, problem) {
-    throw new Error(`gen:section injection failed in ${where}: ${problem} (contract: ${GUIDE})`);
-}
+const fail = failing('gen:section injection failed', GUIDE);
 function addSource(project, root, path, missing) {
     if (!existsSync(`${root}/${path}`))
         fail(path, missing);
@@ -71,23 +70,27 @@ function assertContextForwardable(fn, targets) {
         fail(targets.barrel, `${targets.schemaFunction} destructures its parameter — name it \`context: SchemaContext\`, so an image section can receive it`);
     }
 }
-export function assertSectionInjectable({ root, collection, camel, kebab, pascal, image = false }) {
+// Gli ancoraggi di una collection a sezioni, senza sapere che sezione stia per nascere: il pre-volo
+// ci aggiunge i controlli sul nome nuovo, `doctor` li guarda e basta.
+export function assertSectionAnchors({ root, collection, project = new Project() }) {
     const targets = sectionTargets(collection);
-    const project = new Project();
     const { barrel, fn, union } = locateUnionArray(project, root, targets, collection.kebab);
+    assertContextForwardable(fn, targets);
+    const obj = locateReturnObject(project, root, targets, collection.kebab);
+    const { page, src } = readSectionedPage(root, targets);
+    return { targets, barrel, fn, union, obj, page, src };
+}
+export function assertSectionInjectable({ root, collection, camel, kebab, pascal }) {
+    const { targets, barrel, union, obj, page, src } = assertSectionAnchors({ root, collection });
     if (inUnion(union, camel)) {
         fail(targets.barrel, `section "${camel}" is already in the union — pick another name`);
     }
-    if (image)
-        assertContextForwardable(fn, targets);
     if (isNameTaken(barrel, `${camel}SectionSchema`)) {
         fail(targets.barrel, `the identifier \`${camel}SectionSchema\` is already taken — the injected import would collide. Pick another name`);
     }
-    const obj = locateReturnObject(project, root, targets, collection.kebab);
     if (obj.getProperty(camel)) {
         fail(targets.dataLayer, `section "${camel}" is already picked in ${targets.dataFunction}`);
     }
-    const { page, src } = readSectionedPage(root, targets);
     const frontmatter = src.split('---')[1] ?? '';
     if (new RegExp(`\\b${pascal}\\b`).test(frontmatter)) {
         fail(page, `the identifier \`${pascal}\` is already used in the frontmatter — the component import would collide. Pick another name`);
@@ -109,9 +112,8 @@ function contextArgument(barrel, fn) {
     return 'context';
 }
 export function injectSection({ root, collection, camel, kebab, pascal, image = false }) {
-    const targets = sectionTargets(collection);
     const project = new Project();
-    const { barrel, fn, union } = locateUnionArray(project, root, targets, collection.kebab);
+    const { targets, barrel, fn, union, obj, page, src: original } = assertSectionAnchors({ root, collection, project });
     if (!barrel.getImportDeclaration((d) => d.getModuleSpecifierValue() === `./${kebab}`)) {
         barrel.addImportDeclaration({
             moduleSpecifier: `./${kebab}`,
@@ -121,12 +123,10 @@ export function injectSection({ root, collection, camel, kebab, pascal, image =
     if (!inUnion(union, camel)) {
         union.addElement(`${camel}SectionSchema(${image ? contextArgument(barrel, fn) : ''})`);
     }
-    const obj = locateReturnObject(project, root, targets, collection.kebab);
     if (!obj.getProperty(camel)) {
         obj.addPropertyAssignment({ name: camel, initializer: `pick('${camel}')` });
     }
     project.saveSync();
-    const { page, src: original } = readSectionedPage(root, targets);
     let src = original;
     const imp = `import ${pascal} from '@/components/${collection.kebab}/${kebab}.astro'`;
     if (!src.includes(imp)) {

package/dist/gen/inject-strings.d.mts

@@ -1,3 +1,6 @@
+export declare function assertDictionaries({ root }: {
+    root: any;
+}): void;
 export declare function assertStringsInjectable({ root, keys }: {
     keys: any;
     root: any;

package/dist/gen/inject-strings.mjs

@@ -1,11 +1,10 @@
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { Project, SyntaxKind } from 'ts-morph';
+import { failing } from './hook-points.mjs';
 const DICTIONARIES = 'src/i18n/strings';
 const GUIDE = 'docs/guides/content-collections.md';
-function fail(where, problem) {
-    throw new Error(`gen:page injection failed in ${where}: ${problem} (contract: ${GUIDE})`);
-}
+const fail = failing('gen:page injection failed', GUIDE);
 function locateObject(file, path, locale) {
     const declaration = file.getVariableDeclaration(locale);
     if (!declaration) {
@@ -37,6 +36,11 @@ function loadDictionaries(root) {
     });
     return { project, dictionaries };
 }
+// La forma dei dizionari, senza sapere quali chiavi stiano per arrivare: il pre-volo ci aggiunge
+// il controllo sulle chiavi nuove, `doctor` la guarda e basta.
+export function assertDictionaries({ root }) {
+    loadDictionaries(root);
+}
 export function assertStringsInjectable({ root, keys }) {
     for (const { path, object } of loadDictionaries(root).dictionaries) {
         for (const key of keys) {

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

@@ -0,0 +1,19 @@
+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. */
+    paths: readonly string[];
+    read: (path: string) => string | undefined;
+}
+export interface Manifest {
+    scripts?: Record<string, string>;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+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(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(files: ProjectFiles): ContractGap[];

package/dist/lib/alignment.js

@@ -0,0 +1,139 @@
+import { mentions } from './workflows.js';
+export const EXPECTED_SCRIPTS = {
+    'check:comments': 'officina check comments',
+    'check:language': 'officina check language',
+    'check:routes': 'officina check routes',
+    'check:roadmap': 'officina check roadmap',
+    'check:placeholders': 'officina check placeholders',
+    'perf:bundle': 'officina check bundle',
+    'smoke:prod': 'officina check smoke',
+    'analytics:verify': 'officina check analytics',
+    lhci: 'officina check lighthouse',
+    'lhci:local': 'officina check lighthouse --local',
+    doctor: 'officina doctor',
+    gen: 'officina gen',
+    'gen:section': 'officina gen section',
+    'gen:page': 'officina gen page',
+    'gen:component': 'officina gen component',
+    'gen:collection': 'officina gen collection',
+    'gen:icons': 'officina gen icons',
+};
+export const CI_STEPS = [
+    'check:language',
+    'check:routes',
+    'check:roadmap',
+    'check:comments',
+    'doctor',
+];
+const MANIFEST = 'package.json';
+export function scriptGaps({ scripts = {} }) {
+    const gaps = [];
+    for (const [name, expected] of Object.entries(EXPECTED_SCRIPTS)) {
+        const actual = scripts[name];
+        if (actual === undefined)
+            gaps.push({ path: MANIFEST, message: `script \`${name}\` assente: atteso \`${expected}\`` });
+        else if (!actual.startsWith(expected))
+            gaps.push({ path: MANIFEST, message: `script \`${name}\` è \`${actual}\`: atteso \`${expected}\`` });
+    }
+    const ci = scripts.ci ?? '';
+    for (const step of CI_STEPS) {
+        if (!ci.includes(`pnpm run ${step}`))
+            gaps.push({ path: MANIFEST, message: `script \`ci\` non lancia \`${step}\`` });
+    }
+    return gaps;
+}
+const RETIRED_DEPENDENCIES = ['plop', 'ts-morph'];
+export function dependencyGaps({ dependencies = {}, devDependencies = {} }) {
+    const declared = { ...dependencies, ...devDependencies };
+    const gaps = RETIRED_DEPENDENCIES.filter((name) => name in declared).map((name) => ({
+        path: MANIFEST,
+        message: `\`${name}\` non serve più al progetto: è una dipendenza di officina`,
+    }));
+    if (!('@elia97/officina' in devDependencies)) {
+        gaps.push({ path: MANIFEST, message: '`@elia97/officina` non è fra le devDependencies' });
+    }
+    return gaps;
+}
+const FROM_PLUGIN = 'arriva dal plugin `metodo`';
+const FROM_PACKAGE = 'arriva da officina';
+const OUT_OF_REPOSITORY = 'sta nella cartella del progetto, fuori dal repository';
+// Una cartella si nomina con la barra finale: corrisponde a qualunque file sotto di lei.
+const LEFTOVERS = [
+    { path: '.claude/agents/', reason: FROM_PLUGIN },
+    { path: '.claude/commands/', reason: FROM_PLUGIN },
+    { path: '.claude/scripts/', reason: FROM_PLUGIN },
+    { path: '.claude/hooks/', reason: FROM_PLUGIN },
+    { path: 'HOW_TO_USE.md', reason: FROM_PLUGIN },
+    { path: 'docs/milestone-templates/', reason: FROM_PLUGIN },
+    { path: 'docs/proposal-templates/', reason: 'i modelli commerciali stanno nel sistema, non nel repository' },
+    { path: 'plopfile.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/gen/', reason: FROM_PACKAGE },
+    { path: 'scripts/templates/', reason: FROM_PACKAGE },
+    { path: 'scripts/check-comments.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/check-language.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/bundle-budget.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/smoke-production.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/lighthouse.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/verify-analytics-coverage.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/gen-icons.mjs', reason: FROM_PACKAGE },
+    { path: 'scripts/gen-icons.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lhci-local.sh', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/bundle-budget.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/smoke-production.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/routes.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/check-comments.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/check-language.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/gtm-container.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/analytics-coverage.ts', reason: FROM_PACKAGE },
+    { path: 'scripts/lib/icons.ts', reason: FROM_PACKAGE },
+    { path: '.github/workflows/vercel-cli.yml', reason: "il pin di Vercel sta nell'action di deploy di officina" },
+    { path: 'docs/PROJECT.md', reason: OUT_OF_REPOSITORY },
+    { path: 'docs/DECISIONS.md', reason: OUT_OF_REPOSITORY },
+    { path: 'docs/RISKS.md', reason: OUT_OF_REPOSITORY },
+    { path: 'docs/INPUTS.md', reason: OUT_OF_REPOSITORY },
+    { path: 'docs/TASK-CONTEXT.md', reason: OUT_OF_REPOSITORY },
+    { path: 'docs/ESTIMATE.md', reason: OUT_OF_REPOSITORY },
+];
+const holds = (paths, target) => target.endsWith('/') ? paths.some((path) => path.startsWith(target)) : paths.includes(target);
+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 (readJson(files, '.claude/settings.json')?.hooks !== undefined) {
+        gaps.push({ path: '.claude/settings.json', message: `blocco \`hooks\` residuo: il guard ${FROM_PLUGIN}` });
+    }
+    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(files) {
+    const gaps = [];
+    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 (!mentions(files.read('lefthook.yml'), LEFTHOOK_PRESET)) {
+        gaps.push({ path: 'lefthook.yml', message: `non estende \`${LEFTHOOK_PRESET}\`` });
+    }
+    return gaps;
+}

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,6 +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,15 +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.
+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 = CONFIG_FILES.map((name) => join(root, name)).find((path) => existsSync(path));
+    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 {