@brandlab-digital/conformance 2.1.0 → 3.0.0

package/dist/engineering.js

@@ -1,11 +1,38 @@
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, posix } from 'node:path';
 import ts from 'typescript';
+import { globMatch } from './glob.js';
+import { collectBrandlabSource, createBrandlabModuleResolver, findImportedCalls, isDirectory, lineOfNode, listModuleReferences, objectPropertyValue, parseBrandlabSourceFile, walkProjectFiles, } from './source-files.js';
+import { describeCapabilities } from './static-rules.js';
 export const ENGINEERING_FAST_COMMANDS = ['typecheck', 'lint', 'test', 'check:unused', 'check:unused:production', 'check:standards'];
+/** The exact fast verification command from the Brandlab 3.0 target (section 6). */
+export const BRANDLAB_EXPECTED_VERIFY_SCRIPT = 'npm run check:standards && npm run typecheck && npm run lint && npm run test && npm run check:unused && npm run check:unused:production';
+/** Scripts whose exact values the 3.0 target fixes; dev and start must exist. */
+export const BRANDLAB_EXPECTED_SCRIPTS = Object.freeze({
+    build: 'next build',
+    typecheck: 'next typegen && tsc --noEmit',
+    lint: 'eslint .',
+    test: 'vitest run',
+    'test:e2e': 'playwright test',
+    'check:unused': 'knip',
+    'check:unused:production': 'knip --production',
+    'check:standards': 'brandlab-verify --mode ci --engineering',
+});
+const SRC_DIRECTORIES = new Set(['app', 'config', 'data', 'content', 'lib', 'components', 'types']);
+const SRC_ROOT_FILES = /^(?:instrumentation(?:-client)?|proxy|mdx-components)\.(?:ts|tsx)$/;
+const COMPONENT_ROLES = new Set(['layout', 'ui', 'sections', 'features', 'page-families']);
+const TEST_DIRECTORIES = new Set(['config', 'data', 'lib', 'components', 'e2e', 'support']);
+const RETIRED_ROOT_DIRECTORIES = ['app', 'components', 'data', 'lib', 'config', 'content', 'hooks', 'context', 'utils', 'src/components/templates'];
+const DEV_TOOLING = ['eslint', 'vitest', '@playwright/test', 'knip'];
+const NEXT_SPECIAL_FILE = /^(?:page|layout|template|loading|error|global-error|not-found|global-not-found|forbidden|unauthorized|default|route|opengraph-image|twitter-image|icon|apple-icon|sitemap|robots|manifest)\.(?:ts|tsx|js|jsx|mdx)$/;
+const CODE_OR_STYLE = /\.(?:[cm]?[jt]sx?|mdx|css)$/;
+const PASCAL_COMPONENT = /^[A-Z][A-Za-z0-9]*\.tsx$/;
+const CAMEL_MODULE = /^[a-z][A-Za-z0-9]*(?:\.d)?\.ts$/;
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 /** Opt-in structural check. Static success must never masquerade as whole-project acceptance. */
 export function checkEngineeringStructure(root) {
     const findings = [];
-    const add = (path, rule, message) => findings.push({ path, rule, message });
+    const add = (path, rule, message, extra = {}) => findings.push({ path, rule, message, severity: extra.severity ?? 'blocker', ...(extra.line ? { line: extra.line } : {}) });
     let pkg = {};
     try {
         pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
@@ -13,74 +40,443 @@ export function checkEngineeringStructure(root) {
     catch {
         add('package.json', 'package-readable', 'A readable package.json is required.');
     }
-    for (const path of ['src/app', 'src/data', 'src/config', 'src/components']) {
-        if (!existsSync(join(root, path)))
-            add(path, 'source-organisation', `Place the corresponding implementation under ${path}.`);
-    }
-    for (const path of ['app', 'components', 'data', 'lib', 'config', 'content', 'src/components/templates']) {
-        if (existsSync(join(root, path)))
-            add(path, 'retired-source-layout', 'Migrate consumers to the current src responsibilities and remove the superseded directory.');
-    }
+    const config = existsSync(join(root, 'brandlab.config.ts')) ? readFileSync(join(root, 'brandlab.config.ts'), 'utf8') : null;
+    const capabilities = describeCapabilities(root, config);
+    inspectCommands(pkg, add);
+    inspectDependencies(pkg, add);
+    inspectLayout(root, capabilities, add);
+    inspectSourceModules(root, add);
+    inspectTests(root, capabilities, add);
+    inspectToolPresets(root, add);
+    inspectDelivery(root, add);
+    return { status: findings.some(finding => finding.severity === 'blocker') ? 'blocked' : 'pass', findings,
+        coverage: 'Static layout, naming, command, dependency-pin, tool-preset, CI, deployment and documentation structure only. This is not engineering-standard completion.',
+        outstandingEvidence: ['Usage and deletion review including assets, configuration and dynamic references', 'Business data and component/style ownership review', 'Clean install, fast checks and production build', 'Full discovered technical URL estate', 'All distinct page families and important browser journeys', 'Exact-source protected Preview', 'Reporting/Ads provider cutover and authorised production verification'] };
+}
+// --- commands (section 6) ----------------------------------------------------
+function inspectCommands(pkg, add) {
     const scripts = pkg.scripts ?? {};
-    for (const command of [...ENGINEERING_FAST_COMMANDS, 'verify', 'build', 'test:e2e']) {
+    for (const command of ['dev', 'start', ...ENGINEERING_FAST_COMMANDS, 'verify', 'build', 'test:e2e']) {
         if (!scripts[command]?.trim())
             add('package.json', 'command-contract', `Missing ${command} command.`);
     }
+    for (const [name, expected] of Object.entries(BRANDLAB_EXPECTED_SCRIPTS)) {
+        const actual = scripts[name]?.trim();
+        if (actual && actual.replace(/\s+/g, ' ') !== expected) {
+            add('package.json', 'script-contract', `${name} must be exactly "${expected}" (found "${actual}").`);
+        }
+    }
+    const verify = scripts.verify?.trim();
+    if (verify) {
+        const unrecognised = splitCommandChain(verify).filter(segment => scriptReferences(segment, scripts) === null);
+        if (unrecognised.length > 0) {
+            add('package.json', 'verification-command-form', `verify may only chain package scripts (npm run <script>, npm test, run-s, run-p); "${unrecognised.join('", "')}" is not recognised. Expected "${BRANDLAB_EXPECTED_VERIFY_SCRIPT}".`);
+        }
+    }
     const reachable = new Set();
-    function visit(name) {
+    const visit = (name) => {
         if (reachable.has(name))
             return;
         reachable.add(name);
-        for (const match of (scripts[name] ?? '').matchAll(/\bnpm\s+run\s+([\w:-]+)/g))
-            visit(match[1]);
-    }
+        for (const segment of splitCommandChain(scripts[name] ?? '')) {
+            for (const reference of scriptReferences(segment, scripts) ?? [])
+                visit(reference);
+        }
+    };
     visit('verify');
     for (const command of ENGINEERING_FAST_COMMANDS) {
         if (!reachable.has(command))
-            add('package.json', 'verification-wiring', `verify must execute ${command}.`);
+            add('package.json', 'verification-wiring', `verify must execute ${command}. Expected "${BRANDLAB_EXPECTED_VERIFY_SCRIPT}".`);
     }
     if (reachable.has('build'))
         add('package.json', 'single-build', 'Keep the production build separate from fast verify; run it once for the final candidate.');
-    if (!/\bknip\b/.test(scripts['check:unused'] ?? '') || /--(?:no-exit-code|max-issues|fix)\b/.test(scripts['check:unused'] ?? '')) {
-        add('package.json', 'unused-graph', 'check:unused must run Knip without bypassing failures or automatically deleting files.');
-    }
-    if (!/\bknip\b[^\n]*--production\b/.test(scripts['check:unused:production'] ?? ''))
-        add('package.json', 'production-graph', 'check:unused:production must run Knip production analysis.');
-    const knip = pkg.devDependencies?.knip;
-    if (!knip || !/^\d+\.\d+\.\d+$/.test(knip))
-        add('package.json', 'unused-tool-pin', 'Pin Knip exactly as a development dependency.');
-    if (!/\bbrandlab-verify\b[^\n]*--engineering\b/.test(scripts['check:standards'] ?? ''))
-        add('package.json', 'standards-wiring', 'check:standards must execute brandlab-verify --engineering.');
-    function inspect(directory) {
-        if (!existsSync(directory))
-            return;
-        for (const entry of readdirSync(directory, { withFileTypes: true })) {
-            const path = join(directory, entry.name);
-            if (entry.isSymbolicLink())
+}
+/** Split a shell command on its chaining operators. */
+export function splitCommandChain(command) {
+    return command.split(/&&|\|\||[;|&]/).map(segment => segment.trim()).filter(Boolean);
+}
+/**
+ * The package scripts one command segment runs, or null when the segment is
+ * not a recognised script invocation (npm run, npm test, run-s, run-p, npm-run-all).
+ */
+export function scriptReferences(segment, scripts) {
+    const words = segment.split(/\s+/).filter(Boolean);
+    while (words[0] && /^[A-Z_][A-Z0-9_]*=/.test(words[0]))
+        words.shift();
+    const [tool, ...rest] = words;
+    if (tool === 'npm') {
+        const [subcommand, ...args] = rest;
+        if (subcommand === 'test' || subcommand === 't')
+            return ['test'];
+        if (subcommand === 'start' || subcommand === 'stop' || subcommand === 'restart')
+            return [subcommand];
+        if (subcommand === 'run' || subcommand === 'run-script') {
+            const name = args.find(arg => !arg.startsWith('-'));
+            return name ? [name] : null;
+        }
+        return null;
+    }
+    if (tool === 'run-s' || tool === 'run-p' || tool === 'npm-run-all') {
+        const patterns = [];
+        for (const word of rest) {
+            if (word === '--')
+                break;
+            if (!word.startsWith('-'))
+                patterns.push(word.replace(/^['"]|['"]$/g, ''));
+        }
+        if (patterns.length === 0)
+            return null;
+        // npm-run-all globs: `*` stays within one `:` segment; a whole `**` segment spans several.
+        return patterns.flatMap(pattern => pattern.includes('*') || pattern.includes('?') || pattern.includes('[')
+            ? Object.keys(scripts).filter(name => globMatch(pattern, name, { separator: ':', globstar: true }))
+            : [pattern]);
+    }
+    return null;
+}
+// --- dependencies (section 1) ------------------------------------------------
+function inspectDependencies(pkg, add) {
+    if (pkg.type !== 'module')
+        add('package.json', 'module-type', 'Declare "type": "module".');
+    const dependencies = { ...pkg.dependencies, ...pkg.devDependencies };
+    for (const tool of DEV_TOOLING) {
+        const spec = pkg.devDependencies?.[tool];
+        if (!spec || !SEMVER.test(spec))
+            add('package.json', 'dev-tooling', `Pin ${tool} exactly as a development dependency.`);
+    }
+    // Packed preflight binds the four Brandlab packages to local file: archives; the evaluator verifies those.
+    const ranges = Object.entries(dependencies)
+        .filter(([name, spec]) => !SEMVER.test(spec) && !(name.startsWith('@brandlab-digital/') && spec.startsWith('file:')))
+        .map(([name, spec]) => `${name}@${spec}`);
+    if (ranges.length > 0)
+        add('package.json', 'exact-pins', `Pin every dependency to the exact locked version: ${ranges.sort().join(', ')}.`);
+    const next = dependencies.next;
+    for (const companion of ['eslint-config-next', '@next/mdx']) {
+        const spec = dependencies[companion];
+        if (spec && spec !== next)
+            add('package.json', 'framework-companion-pin', `${companion} must equal the next version (${next ?? 'missing'}); found ${spec}.`);
+    }
+    if (!dependencies['eslint-config-next'])
+        add('package.json', 'framework-companion-pin', 'Declare eslint-config-next at the exact next version for brandlab.configs.next.');
+    if (pkg.dependencies?.sharp || pkg.devDependencies?.sharp)
+        add('package.json', 'sharp-override-only', 'Remove the direct sharp dependency; the release-owned overrides.sharp pin is the only declaration.');
+}
+// --- layout and naming (section 2) --------------------------------------------
+function inspectLayout(root, capabilities, add) {
+    for (const path of ['src/app', 'src/config', 'src/data', 'src/lib', 'src/components', 'tests']) {
+        if (!isDirectory(join(root, path)))
+            add(path, 'source-organisation', `Place the corresponding implementation under ${path}.`);
+    }
+    for (const path of RETIRED_ROOT_DIRECTORIES) {
+        if (existsSync(join(root, path)))
+            add(path, 'retired-source-layout', 'Migrate consumers to the current src responsibilities and remove the superseded directory.');
+    }
+    const required = [
+        'src/config/site.ts', 'src/config/analytics.ts', 'src/data/business.ts', 'src/data/routes.ts', 'src/data/redirects.ts',
+        'src/lib/seo/metadata.ts', 'src/instrumentation-client.ts', 'src/app/layout.tsx', 'src/app/robots.ts', 'src/app/sitemap.xml/route.ts',
+        ...(capabilities.contactEnabled ? ['src/config/contact.ts', 'src/app/api/contact/route.ts'] : []),
+        ...(capabilities.reviewsEnabled ? ['src/config/reviews.ts'] : []),
+        ...(capabilities.locationsDeclared ? ['src/data/locations/estate.ts'] : []),
+    ];
+    for (const path of required) {
+        if (!existsSync(join(root, path)))
+            add(path, 'owner-file', `The 3.0 layout places this owner at ${path}.`);
+    }
+    for (const [path, message] of [
+        ['src/config/env.ts', 'Remove the local environment parser; site configuration is a source constant.'],
+        ['src/lib/analytics', 'Remove the local analytics layer; installBrandlabInstrumentation owns it.'],
+        ['src/lib/contact/definition.ts', 'Remove the local contact definition; the contract lives in src/config/contact.ts.'],
+        ['src/lib/contact/constants.ts', 'Remove the local contact constants; the contract lives in src/config/contact.ts.'],
+        ['src/lib/contact/runtime.ts', 'Remove the local contact runtime; POST uses createBrandlabContactRouteHandler.'],
+        ['src/components/analytics/GoogleTag.tsx', 'Render BrandlabGoogleTag directly in src/app/layout.tsx.'],
+        ['src/components/analytics/CoreWebVitalsReporter.tsx', 'Remove the web-vitals reporter.'],
+        ['src/lib/seo/sitemaps', 'Remove the local sitemap builders; the sitemap route uses createBrandlabSitemapRoute.'],
+        ['src/lib/seo/sitemaps.ts', 'Remove the local sitemap builders; the sitemap route uses createBrandlabSitemapRoute.'],
+        ['src/lib/seo/schema/sanitize.ts', 'Remove the local schema sanitiser; the packages own sanitising.'],
+        ['src/lib/seo/schema/SchemaScript.tsx', 'Import SchemaScript from @brandlab-digital/site-next/schema.'],
+        ['src/lib/seo/index.ts', 'Remove the SEO barrel and import each module directly.'],
+    ]) {
+        if (existsSync(join(root, path)))
+            add(path, 'retired-file', message);
+    }
+    if (isDirectory(join(root, 'src'))) {
+        for (const entry of readdirSync(join(root, 'src'), { withFileTypes: true })) {
+            if (entry.name.startsWith('.'))
                 continue;
-            if (entry.isDirectory()) {
-                inspect(path);
+            const path = `src/${entry.name}`;
+            if (entry.isDirectory() && SRC_DIRECTORIES.has(entry.name)) {
+                if (entry.name === 'types' && walkProjectFiles(root, path).some(file => !file.endsWith('.d.ts'))) {
+                    add(path, 'standard-layout', 'src/types may hold only ambient .d.ts declarations.');
+                }
                 continue;
             }
-            if (!/\.(?:tsx?|jsx?|mjs|cjs)$/.test(entry.name) || /\.(?:test|spec)\./.test(entry.name))
+            if (entry.isFile() && SRC_ROOT_FILES.test(entry.name))
                 continue;
-            const source = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true);
-            const location = relative(root, path).replaceAll('\\', '/');
-            function walk(node) {
-                if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith('@brandlab-digital/')) {
-                    const bindings = node.importClause?.namedBindings;
-                    if (bindings && ts.isNamedImports(bindings) && bindings.elements.some(element => (element.propertyName ?? element.name).text === 'trackPhoneCall')) {
-                        add(location, 'retired-phone-api', 'Use trackPhoneLinkClick; the deprecated alias is removed in the current major.');
-                    }
+            add(path, 'standard-layout', `${path} is outside the standard layout (src/{app,config,data,content,lib,components}).`);
+        }
+    }
+    if (isDirectory(join(root, 'src/components'))) {
+        for (const entry of readdirSync(join(root, 'src/components'), { withFileTypes: true })) {
+            if (entry.name.startsWith('.') || entry.name === 'templates')
+                continue;
+            if (!entry.isDirectory() || !COMPONENT_ROLES.has(entry.name)) {
+                add(`src/components/${entry.name}`, 'component-role', 'Components belong to one role: layout, ui, sections, features or page-families.');
+            }
+        }
+    }
+    for (const path of walkProjectFiles(root, 'src'))
+        inspectFileName(root, path, add);
+}
+function inspectFileName(root, path, add) {
+    const name = posix.basename(path);
+    const directory = posix.dirname(path);
+    if (directory === 'src' && SRC_ROOT_FILES.test(name))
+        return;
+    if (name.endsWith('.module.css')) {
+        const component = name.replace(/\.module\.css$/, '');
+        if (!['tsx', 'ts', 'jsx'].some(extension => existsSync(join(root, directory, `${component}.${extension}`)))) {
+            add(path, 'file-naming', `Keep ${name} beside the ${component} component it styles.`);
+        }
+        return;
+    }
+    if (path.startsWith('src/app/')) {
+        // Images, fonts and metadata assets are framework-consumed; only code and styles are placed.
+        if (!CODE_OR_STYLE.test(name))
+            return;
+        const segments = path.split('/');
+        const privateFolder = segments.slice(2, -1).find(segment => segment.startsWith('_') && segment !== '_components');
+        if (privateFolder) {
+            add(path, 'route-local-code', `Route-local code belongs in src/app/<route>/_components/, not ${privateFolder}/.`);
+            return;
+        }
+        if (!segments.includes('_components')) {
+            if (NEXT_SPECIAL_FILE.test(name) || path === 'src/app/globals.css')
+                return;
+            add(path, 'route-local-code', 'Route-local code belongs in src/app/<route>/_components/; framework files keep their reserved names.');
+            return;
+        }
+    }
+    if (!/\.(?:ts|tsx)$/.test(name) || path.startsWith('src/content/'))
+        return;
+    if (name.endsWith('.tsx') && !PASCAL_COMPONENT.test(name)) {
+        add(path, 'file-naming', 'Components use PascalCase .tsx file names.');
+    }
+    else if (name.endsWith('.ts') && !CAMEL_MODULE.test(name)) {
+        add(path, 'file-naming', 'Data and helper modules use camelCase .ts file names.');
+    }
+    if (path.startsWith('src/components/page-families/') && name.endsWith('.tsx') && !/^[A-Z][A-Za-z0-9]*Page\.tsx$/.test(name)) {
+        add(path, 'file-naming', 'Page families are named <RouteKind>Page.tsx.');
+    }
+}
+// --- module structure: barrels, ui data imports, estate ----------------------
+function inspectSourceModules(root, add) {
+    const source = collectBrandlabSource(root);
+    const resolver = createBrandlabModuleResolver(root, new Set(source.byPath.keys()));
+    for (const file of source.files.filter(candidate => candidate.path.startsWith('src/'))) {
+        const references = listModuleReferences(file);
+        const forwarding = forwardingExports(file);
+        if (isBarrel(file)) {
+            add(file.path, 'no-barrels', 'This module only re-exports other modules; import each owner directly.');
+        }
+        else {
+            for (const line of forwarding) {
+                add(file.path, 'no-forwarding-exports', 'This export forwards another module; import the owner directly.', { line });
+            }
+        }
+        if (file.path.startsWith('src/components/ui/')) {
+            for (const reference of references.filter(candidate => candidate.kind !== 'export')) {
+                const resolved = resolver(file.path, reference.specifier);
+                if (resolved?.startsWith('src/data/') || /^@\/data(?:\/|$)/.test(reference.specifier)) {
+                    add(file.path, 'ui-imports-data', 'UI primitives never import data modules; pass prepared props from a section or route.', { line: reference.line });
                 }
-                ts.forEachChild(node, walk);
             }
-            walk(source);
         }
+        inspectRegistryDerivedEstate(file, add);
     }
-    inspect(join(root, 'src'));
-    return { status: findings.length ? 'blocked' : 'pass', findings,
-        coverage: 'Static source organisation, command wiring and retired API imports only. This is not engineering-standard completion.',
-        outstandingEvidence: ['Usage and deletion review including assets, configuration and dynamic references', 'Business data and component/style ownership review', 'Clean install, fast checks and production build', 'Full discovered technical URL estate', 'All distinct page families and important browser journeys', 'Exact-source protected Preview', 'Reporting/Ads provider cutover and authorised production verification'] };
+    const estate = source.byPath.get('src/data/locations/estate.ts');
+    if (estate) {
+        inspectRetainedExclusions(estate, add);
+        inspectSiteOwnedLocations(estate, add);
+    }
+}
+/** Lines of `export ... from` statements and exports of names this module only imported. */
+function forwardingExports(file) {
+    const source = parseBrandlabSourceFile(file);
+    const imported = new Set(listModuleReferences(file).filter(reference => reference.kind === 'import').flatMap(reference => reference.bindings.map(binding => binding.local)));
+    const lines = [];
+    for (const statement of source.statements) {
+        const forwards = (ts.isExportDeclaration(statement) && (statement.moduleSpecifier !== undefined ||
+            (statement.exportClause !== undefined && ts.isNamedExports(statement.exportClause) &&
+                statement.exportClause.elements.some(element => imported.has((element.propertyName ?? element.name).text))))) ||
+            (ts.isExportAssignment(statement) && ts.isIdentifier(statement.expression) && imported.has(statement.expression.text));
+        if (forwards)
+            lines.push(lineOfNode(file, statement));
+    }
+    return lines;
+}
+/** A module with no declarations or statements of its own besides imports and exports. */
+function isBarrel(file) {
+    const statements = parseBrandlabSourceFile(file).statements;
+    return statements.length > 0 && forwardingExports(file).length > 0 &&
+        statements.every(statement => ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement) || ts.isExportAssignment(statement));
+}
+function inspectRegistryDerivedEstate(file, add) {
+    const derived = listModuleReferences(file)
+        .filter(reference => reference.kind === 'import' && /^@brandlab-digital\/site-core\//.test(reference.specifier))
+        .flatMap(reference => reference.bindings.filter(binding => /WebsiteSuburbs$/.test(binding.imported)).map(binding => ({ ...binding, line: reference.line })));
+    const namespaceUse = file.executable.match(/\.\s*([a-z][A-Za-z]*WebsiteSuburbs)\b/);
+    const first = derived[0] ?? (namespaceUse ? { imported: namespaceUse[1], line: lineAtIndex(file.text, namespaceUse.index ?? 0) } : null);
+    if (!first)
+        return;
+    add(file.path, 'estate-registry-derived', `${first.imported} is a registry candidate list; the published estate in src/data/locations/estate.ts must be literal data, never derived from it.`, { line: first.line });
+}
+function inspectRetainedExclusions(file, add) {
+    for (const call of findImportedCalls(file, /^@brandlab-digital\/site-core\/locations$/, 'defineLocationEstate')) {
+        const retained = objectPropertyValue(call.arguments[0], 'retainedExclusions');
+        if (!retained || !ts.isArrayLiteralExpression(retained) || retained.elements.length === 0)
+            continue;
+        const slugs = retained.elements.map(element => {
+            if (ts.isStringLiteralLike(element))
+                return element.text;
+            const slug = objectPropertyValue(element, 'slug');
+            return slug && ts.isStringLiteralLike(slug) ? slug.text : null;
+        }).filter((slug) => Boolean(slug));
+        add(file.path, 'estate-retained-exclusions', `${retained.elements.length} policy-excluded location(s) stay published for a later SEO decision${slugs.length ? `: ${slugs.join(', ')}` : ''}.`, { severity: 'info', line: lineOfNode(file, retained) });
+    }
+}
+/** An array literal, directly or through a top-level `const name = [...]` (optionally `as const`) in the same file. */
+function arrayLiteral(file, node) {
+    const unwrap = (expression) => {
+        let current = expression;
+        while (current && (ts.isAsExpression(current) || ts.isSatisfiesExpression(current) || ts.isParenthesizedExpression(current))) {
+            current = current.expression;
+        }
+        return current;
+    };
+    const value = unwrap(node);
+    if (value && ts.isArrayLiteralExpression(value))
+        return value;
+    if (!value || !ts.isIdentifier(value))
+        return undefined;
+    for (const statement of parseBrandlabSourceFile(file).statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) && declaration.name.text === value.text) {
+                const initializer = unwrap(declaration.initializer);
+                return initializer && ts.isArrayLiteralExpression(initializer) ? initializer : undefined;
+            }
+        }
+    }
+    return undefined;
+}
+/** Report the locations the site publishes outside the shared registry, with each group's reason. */
+function inspectSiteOwnedLocations(file, add) {
+    for (const call of findImportedCalls(file, /^@brandlab-digital\/site-core\/locations$/, 'defineLocationEstate')) {
+        const declared = objectPropertyValue(call.arguments[0], 'siteOwned');
+        if (!declared)
+            continue;
+        const groups = arrayLiteral(file, declared);
+        if (!groups) {
+            add(file.path, 'estate-site-owned', 'siteOwned must be literal data in src/data/locations/estate.ts: [{ reason, slugs }], never derived.', { line: lineOfNode(file, declared) });
+            continue;
+        }
+        if (groups.elements.length === 0)
+            continue;
+        let total = 0;
+        const summaries = groups.elements.map(element => {
+            const reason = objectPropertyValue(element, 'reason');
+            const slugs = arrayLiteral(file, objectPropertyValue(element, 'slugs'));
+            const count = slugs?.elements.length;
+            total += count ?? 0;
+            const label = reason && ts.isStringLiteralLike(reason) ? reason.text : 'a reason that is not a string literal';
+            return `${count ?? 'an unknown number of'} for "${label}"`;
+        });
+        add(file.path, 'estate-site-owned', `${total} location(s) are published outside the shared geography registry, declared site-owned: ${summaries.join('; ')}.`, { severity: 'info', line: lineOfNode(file, groups) });
+    }
+}
+function lineAtIndex(text, index) {
+    return text.slice(0, index).split('\n').length;
+}
+// --- tests (sections 2 and 6) -------------------------------------------------
+function inspectTests(root, capabilities, add) {
+    if (!isDirectory(join(root, 'tests')))
+        return;
+    for (const entry of readdirSync(join(root, 'tests'), { withFileTypes: true })) {
+        if (entry.name.startsWith('.'))
+            continue;
+        if (!entry.isDirectory() || !TEST_DIRECTORIES.has(entry.name)) {
+            add(`tests/${entry.name}`, 'test-layout', 'Tests live in tests/{config,data,lib,components,e2e,support}.');
+        }
+    }
+    const required = [
+        'tests/data/routes.test.ts', 'tests/config/analytics.test.ts',
+        'tests/e2e/estate.spec.ts', 'tests/e2e/analytics.spec.ts', 'tests/e2e/families.spec.ts',
+        ...(capabilities.contactEnabled ? ['tests/config/contact.test.ts', 'tests/e2e/contact.spec.ts'] : []),
+    ];
+    for (const path of required) {
+        if (!existsSync(join(root, path)))
+            add(path, 'shared-tests', `The shared 3.0 test set includes ${path}.`);
+    }
+    for (const path of walkProjectFiles(root, 'tests')) {
+        if (/-darwin\.png$/.test(path))
+            add(path, 'committed-snapshots', 'Delete committed darwin snapshots; rendered checks run against the CI build.');
+    }
+}
+// --- dev presets (section 4) -------------------------------------------------
+function inspectToolPresets(root, add) {
+    const eslint = readOptional(join(root, 'eslint.config.mjs'));
+    if (eslint === null)
+        add('eslint.config.mjs', 'tool-preset', 'Add eslint.config.mjs: export default brandlab.configs.next.');
+    else if (!/@brandlab-digital\/eslint-plugin/.test(eslint) || !/export\s+default\s+[A-Za-z_$][\w$]*\.configs\.next\s*;?\s*$/.test(eslint.trim())) {
+        add('eslint.config.mjs', 'tool-preset', 'eslint.config.mjs is exactly `export default brandlab.configs.next` (imported from @brandlab-digital/eslint-plugin).');
+    }
+    const knip = readOptional(join(root, 'knip.ts'));
+    if (knip === null)
+        add('knip.ts', 'tool-preset', 'Add knip.ts: export default brandlabKnip({ mdx?, entry? }).');
+    else if (!/@brandlab-digital\/conformance\/knip/.test(knip) || !/export\s+default\s+brandlabKnip\s*\(/.test(knip)) {
+        add('knip.ts', 'tool-preset', 'knip.ts exports brandlabKnip({ mdx?, entry? }) from @brandlab-digital/conformance/knip.');
+    }
+    if (!['playwright.config.ts', 'playwright.config.mts'].some(name => existsSync(join(root, name)))) {
+        add('playwright.config.ts', 'tool-preset', 'Add the Playwright configuration for the shared e2e specs.');
+    }
+    if (!['vitest.config.ts', 'vitest.config.mts'].some(name => existsSync(join(root, name)))) {
+        add('vitest.config.ts', 'tool-preset', 'Add the Vitest configuration for the binding tests.');
+    }
+}
+// --- CI, dependencies, Vercel and docs (section 6) ---------------------------
+function inspectDelivery(root, add) {
+    const workflowDirectory = join(root, '.github/workflows');
+    const workflows = isDirectory(workflowDirectory) ? readdirSync(workflowDirectory).filter(name => /\.ya?ml$/.test(name)).sort() : [];
+    const callers = workflows.filter(name => /uses\s*:\s*['"]?RomieDandan\/brandlab\/\.github\/workflows\/verify-next\.yml@/.test(readFileSync(join(workflowDirectory, name), 'utf8')));
+    if (callers.length !== 1 || callers[0] !== 'verify.yml') {
+        add('.github/workflows/verify.yml', 'ci-workflow', `Exactly one .github/workflows/verify.yml calls RomieDandan/brandlab/.github/workflows/verify-next.yml at the fleet SHA (found ${callers.length ? callers.join(', ') : 'none'}).`);
+    }
+    for (const path of ['.github/dependabot.yml', '.github/dependabot.yaml', 'renovate.json', 'renovate.json5', '.github/renovate.json', '.renovaterc', '.renovaterc.json']) {
+        if (existsSync(join(root, path)))
+            add(path, 'dependency-bots', 'Exact pins move with Brandlab releases; remove Dependabot/Renovate version updates.');
+    }
+    const vercel = readOptional(join(root, 'vercel.json'));
+    let installCommand;
+    try {
+        installCommand = vercel === null ? undefined : JSON.parse(vercel).installCommand;
+    }
+    catch {
+        installCommand = undefined;
+    }
+    if (installCommand !== 'npm ci')
+        add('vercel.json', 'vercel-install', 'vercel.json sets installCommand to "npm ci" (keep any existing regions).');
+    if (!existsSync(join(root, 'README.md')))
+        add('README.md', 'project-docs', 'Add the generated README.md (commands, architecture, environment names, deployment and rollback).');
+    const agents = join(root, 'AGENTS.md');
+    if (!existsSync(agents))
+        add('AGENTS.md', 'project-docs', 'Add AGENTS.md with the fixed sources of truth and guardrails.');
+    else if (statSync(agents).size > 3_584)
+        add('AGENTS.md', 'project-docs', `AGENTS.md is ${statSync(agents).size} bytes; keep it to about 3 KB and archive history to the control repo.`);
+    const claude = readOptional(join(root, 'CLAUDE.md'));
+    if (claude === null || claude.trim() !== '@AGENTS.md')
+        add('CLAUDE.md', 'project-docs', 'CLAUDE.md is the single line @AGENTS.md.');
+}
+function readOptional(path) {
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
 }
 //# sourceMappingURL=engineering.js.map