@heshammesalam/heshjs 0.2.0 → 0.3.0

package/src/architecture/index.ts

@@ -0,0 +1,283 @@
+import ts from 'typescript';
+import { readFileSync, existsSync, realpathSync, mkdirSync, writeFileSync, statSync } from 'node:fs';
+import { resolve, dirname, relative, extname, join } from 'node:path';
+import { parse, HeshError, type Module, type Contract, type ContractEntry } from '../parser/index.js';
+import { compileHTML } from './html.js';
+import { diagnostic, formatDiagnostic, type ArchitectureDiagnostic } from './diagnostics.js';
+export { compileHTML, formatDiagnostic };
+export type { ArchitectureDiagnostic };
+export interface ProjectOptions { root: string; entry?: string; tsconfig?: string; outDir?: string }
+export interface ProjectResult {
+  diagnostics: ArchitectureDiagnostic[]; files: string[]; outputs: Record<string, string>;
+  graph: { domains: { name: string; exposes: string[]; consumes: string[] }[]; destinations: { name: string; url: string; input: Record<string, string>; owner: string }[]; links: { from: string; to: string }[] };
+  statistics: { parsed: number; reused: number };
+}
+interface Located { node: Contract; file: string; source: string }
+interface Factory { file: string; name: string; result: ts.Type }
+const canonical = (file: string) => {
+  const path = resolve(file); const real = existsSync(path) ? realpathSync(path) : path;
+  return (ts.sys.useCaseSensitiveFileNames ? real : real.toLowerCase()).replace(/\\/g, '/');
+};
+const inside = (file: string, folder: string) => file === folder || file.startsWith(folder + '/');
+const isFile = (file: string) => existsSync(file) && statSync(file).isFile();
+const modulePath = (from: string, to: string) => { const path = relative(dirname(from), to).replace(/\\/g, '/'); return path.startsWith('.') ? path : './' + path; };
+export function createArchitectureCompiler() {
+  const cache = new Map<string, { source: string; ast: Module }>();
+  return { clear() { cache.clear(); }, check(options: ProjectOptions): ProjectResult {
+    const root = canonical(options.root), entry = canonical(resolve(root, options.entry ?? 'app.hesh'));
+    const outDir = resolve(root, options.outDir ?? '.hesh-generated');
+    const diagnostics: ArchitectureDiagnostic[] = [], descriptors = new Map<string, Module>(), declarations = new Map<string, Located>();
+    const files = new Set<string>(); let parsed = 0, reused = 0;
+    const error = (code: string, message: string, item: Located, position = item.node.start, suggestion = 'Correct the declared contract.') => diagnostics.push(diagnostic(code, message, item.file, item.source, position, suggestion));
+    const read = (file: string): string => { files.add(file); return readFileSync(file, 'utf8'); };
+    const load = (file: string): void => {
+      if (descriptors.has(file)) return;
+      if (!inside(file, root) || !isFile(file)) { diagnostics.push(diagnostic('HESH-ARCH-001', 'Missing or out-of-project descriptor', file, '', 0, 'Import an existing .hesh file within the application root.')); return; }
+      const source = read(file); let ast: Module;
+      try {
+        const saved = cache.get(file);
+        if (saved?.source === source) { ast = saved.ast; reused++; }
+        else { ast = parse(source, file); cache.set(file, { source, ast }); parsed++; }
+      } catch (failure) {
+        diagnostics.push(diagnostic('HESH-SYNTAX-001', failure instanceof Error ? failure.message : String(failure), file, source, failure instanceof HeshError ? failure.offset : 0, 'Fix the Hesh declaration syntax.')); return;
+      }
+      descriptors.set(file, ast);
+      if (ast.views.length) diagnostics.push(diagnostic('HESH-ARCH-001', 'Architecture descriptor files cannot also contain view implementations', file, source, ast.views[0]!.start, 'Keep existing .hesh views in separate component files.'));
+      for (const node of ast.contracts ?? []) {
+        const item = { node, file, source };
+        if (declarations.has(node.name)) error('HESH-ARCH-002', `Duplicate declaration ${node.name}`, item);
+        else declarations.set(node.name, item);
+      }
+      for (const item of ast.imports) {
+        const syntax = ts.createSourceFile(file, item.source, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+        const statement = syntax.statements[0];
+        if (!statement || !ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || statement.importClause || !statement.moduleSpecifier.text.endsWith('.hesh')) {
+          diagnostics.push(diagnostic('HESH-ARCH-001', 'Architecture imports must be side-effect imports of .hesh descriptors', file, source, item.start, 'Use import "./domains/inventory/domain.hesh";.')); continue;
+        }
+        load(canonical(resolve(dirname(file), statement.moduleSpecifier.text)));
+      }
+    };
+    load(entry);
+    const all = [...declarations.values()];
+    const applications = all.filter(d => d.node.kind === 'application');
+    const app = applications[0];
+    if (applications.length !== 1) diagnostics.push(diagnostic('HESH-ARCH-001', 'Exactly one application declaration is required', entry, descriptors.get(entry)?.source ?? '', 0, 'Declare one application listing domains and destinations.'));
+    const select = (kind: Contract['kind'], names: ContractEntry[] | undefined) => (names ?? []).flatMap(name => {
+      const target = declarations.get(name.name);
+      if (!target || target.node.kind !== kind) { if (app) error('HESH-ARCH-003', `Missing ${kind} ${name.name}`, app, name.start); return []; }
+      return [target];
+    });
+    const domains = select('domain', app?.node.blocks.domains), destinations = select('destination', app?.node.blocks.destinations);
+    const presentations = all.filter(d => d.node.kind === 'presentation');
+    const declaredDomains = all.filter(d => d.node.kind === 'domain');
+    const owner = (file: string): Located | undefined => declaredDomains.filter(d => inside(file, canonical(dirname(d.file)))).sort((a, b) => dirname(b.file).length - dirname(a.file).length)[0];
+    const field = (item: Located, name: string, required = true) => {
+      const value = item.node.fields[name]?.value;
+      if (required && !value) error('HESH-ARCH-003', `Missing field ${name} in ${item.node.name}`, item);
+      return value ?? '';
+    };
+    const list = (item: Located, name: string, required = false): ContractEntry[] => {
+      if (required && !item.node.blocks[name]) error('HESH-ARCH-003', `Missing block ${name}`, item);
+      return item.node.blocks[name] ?? [];
+    };
+    if (app) { list(app, 'domains', true); list(app, 'destinations', true); }
+    const factories = new Map<Located, { file: string; name: string }>();
+    for (const item of [...domains, ...presentations]) {
+      const specifier = field(item, item.node.kind === 'domain' ? 'implementation' : 'logic');
+      const hash = specifier.lastIndexOf('#'), path = specifier.slice(0, hash), name = specifier.slice(hash + 1);
+      if (hash < 1 || !/^[$_\p{ID_Start}][$_\u200c\u200d\p{ID_Continue}]*$/u.test(name) || !path.startsWith('.') || !['.js', '.ts', '.mjs'].includes(extname(path)) || path.endsWith('.d.ts')) { error('HESH-ARCH-003', `Invalid implementation reference ${specifier}`, item, item.node.start, 'Use ./module.js#exportName (or .ts/.mjs).'); continue; }
+      const file = canonical(resolve(dirname(item.file), path));
+      if (!existsSync(file) || !inside(file, root) || owner(file) !== owner(item.file)) { error('HESH-ARCH-004', `Implementation must exist inside its owning domain: ${specifier}`, item); continue; }
+      factories.set(item, { file, name }); files.add(file);
+    }
+    const byDomain = new Map(domains.map(item => [item.node.name, item]));
+    for (const item of declaredDomains) if (declaredDomains.some(other => other !== item && dirname(other.file) === dirname(item.file))) error('HESH-ARCH-002', 'Each domain needs its own directory boundary', item);
+    const edges = new Map<string, string[]>();
+    for (const item of domains) {
+      const exposes = list(item, 'exposes', true).map(v => v.name);
+      if (!exposes.length) error('HESH-ARCH-003', `Domain ${item.node.name} must expose at least one operation`, item);
+      for (const name of exposes) if (exposes.some(other => other !== name && other.startsWith(name + '.'))) error('HESH-ARCH-003', `Overlapping public operation ${name}`, item);
+      const dependencies: string[] = [];
+      for (const consume of list(item, 'consumes')) {
+        const [provider, ...path] = consume.name.split('.'), target = byDomain.get(provider!);
+        if (!target || !path.length || !list(target, 'exposes').some(v => v.name === path.join('.'))) error('HESH-ARCH-003', `Unresolved consumed operation ${consume.name}`, item, consume.start, 'Consume an operation explicitly exposed by a selected domain.');
+        dependencies.push(provider!);
+      }
+      for (const policy of list(item, 'access')) if (!exposes.includes(policy.name)) error('HESH-ARCH-003', `Access policy refers to unexposed operation ${policy.name}`, item, policy.start);
+      edges.set(item.node.name, dependencies);
+    }
+    const visited = new Set<string>(), visiting: string[] = [];
+    const visit = (name: string) => {
+      if (visiting.includes(name)) { const item = byDomain.get(name); if (item) error('HESH-ARCH-005', `Circular dependency: ${[...visiting, name].join(' -> ')}`, item, item.node.start, 'Remove the cycle or extract an explicit shared contract.'); return; }
+      if (visited.has(name)) return;
+      visiting.push(name); for (const next of edges.get(name) ?? []) visit(next); visiting.pop(); visited.add(name);
+    };
+    for (const name of byDomain.keys()) visit(name);
+    let settings: ts.CompilerOptions = { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.Bundler, allowJs: true, checkJs: true, noEmit: true, skipLibCheck: true, allowImportingTsExtensions: true, types: [] };
+    if (options.tsconfig) {
+      const configFile = resolve(root, options.tsconfig), config = ts.readConfigFile(configFile, ts.sys.readFile);
+      if (config.error) diagnostics.push(diagnostic('HESH-ARCH-001', ts.flattenDiagnosticMessageText(config.error.messageText, '\n'), configFile, '', 0, 'Correct the TypeScript project configuration.'));
+      else settings = { ...settings, ...ts.parseJsonConfigFileContent(config.config, ts.sys, dirname(configFile)).options, noEmit: true, allowJs: true, checkJs: true };
+    }
+    const program = ts.createProgram([...factories.values()].map(f => f.file), settings);
+    const checker = program.getTypeChecker();
+    const resolvedFactories = new Map<Located, Factory>();
+    const getMember = (type: ts.Type, path: string[], unwrap = false): ts.Type | undefined => {
+      let current = type;
+      const unwrapped = (value: ts.Type): ts.Type => {
+        const get = checker.getPropertyOfType(value, 'get');
+        const callable = get ? checker.getTypeOfSymbolAtLocation(get, get.valueDeclaration ?? program.getSourceFiles()[0]!) : value;
+        return checker.getSignaturesOfType(callable, ts.SignatureKind.Call)[0]?.getReturnType() ?? value;
+      };
+      for (const piece of path) {
+        if (unwrap) current = unwrapped(current);
+        if (current.flags & ts.TypeFlags.Any) return current;
+        const symbol = checker.getPropertyOfType(current, piece); if (!symbol) return;
+        current = checker.getTypeOfSymbolAtLocation(symbol, symbol.valueDeclaration ?? program.getSourceFiles()[0]!);
+      }
+      return unwrap ? unwrapped(current) : current;
+    };
+    for (const [item, reference] of factories) {
+      const sourceFile = program.getSourceFile(reference.file);
+      const symbol = sourceFile && checker.getSymbolAtLocation(sourceFile);
+      let exported = symbol && checker.getExportsOfModule(symbol).find(v => v.name === reference.name);
+      if (exported?.flags && exported.flags & ts.SymbolFlags.Alias) exported = checker.getAliasedSymbol(exported);
+      const type = exported && checker.getTypeOfSymbolAtLocation(exported, exported.valueDeclaration ?? sourceFile!);
+      const signature = type && checker.getSignaturesOfType(type, ts.SignatureKind.Call)[0];
+      if (!signature) { error('HESH-ARCH-003', `Missing callable export ${reference.name} in ${reference.file}`, item); continue; }
+      const result = signature.getReturnType();
+      if (result.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown) || checker.getPropertyOfType(result, 'then')) { error('HESH-ARCH-003', `Factory ${reference.name} must return a statically inspectable synchronous object`, item); continue; }
+      resolvedFactories.set(item, { ...reference, result });
+      if (item.node.kind === 'domain') for (const operation of list(item, 'exposes')) {
+        const target = getMember(result, operation.name.split('.'));
+        if (!target || !checker.getSignaturesOfType(target, ts.SignatureKind.Call).length) error('HESH-ARCH-003', `Unresolved callable implementation ${item.node.name}.${operation.name}`, item, operation.start, 'Return this operation from the declared implementation factory.');
+      }
+      else for (const block of ['bindings', 'actions']) {
+        if (!getMember(result, [block])) error('HESH-BIND-002', `Presentation factory must return a ${block} object`, item);
+        for (const binding of list(item, block, true)) {
+          const target = getMember(result, [block, binding.name]);
+          if (!target || (block === 'actions' && !checker.getSignaturesOfType(target, ts.SignatureKind.Call).length)) error(block === 'actions' ? 'HESH-ACTION-001' : 'HESH-BIND-002', `Missing ${block} implementation ${binding.name}`, item, binding.start, `Return ${block}.${binding.name} from the presentation factory.`);
+        }
+      }
+    }
+    // Validate actual imports/re-exports, including aliases and files shared by domains.
+    const sources = ts.sys.readDirectory(root, ['.ts', '.js', '.mjs'], ['**/node_modules/**', '**/dist/**', '**/.hesh-generated/**'], ['**/*']);
+    for (const path of sources) {
+      const file = canonical(path); if (inside(file, canonical(outDir))) continue;
+      files.add(file); const source = read(file), syntax = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, file.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS);
+      const checkImport = (specifier: ts.Node | undefined): void => {
+        if (!specifier) return;
+        if (!ts.isStringLiteralLike(specifier)) { diagnostics.push(diagnostic('HESH-ARCH-007', 'Computed module imports cannot be architecture-validated', file, source, specifier.getStart(syntax), 'Use literal imports and explicit injected dependencies.')); return; }
+        if (specifier.text.startsWith('node:') || ['fs', 'path', 'child_process', 'worker_threads', 'net', 'tls', 'http', 'https', 'os', 'module'].includes(specifier.text)) {
+          diagnostics.push(diagnostic('HESH-SEC-001', `Node/server-only import in client code: ${specifier.text}`, file, source, specifier.getStart(syntax), 'Call server infrastructure through an API rather than bundling it.')); return;
+        }
+        const target = ts.resolveModuleName(specifier.text, file, settings, ts.sys).resolvedModule?.resolvedFileName;
+        const generated = canonical(resolve(dirname(file), specifier.text));
+        if (inside(generated, canonical(outDir))) return;
+        if (!target) { if (!specifier.text.endsWith('.css') && !specifier.text.endsWith('.hesh')) diagnostics.push(diagnostic('HESH-ARCH-006', `Unresolved module ${specifier.text}`, file, source, specifier.getStart(syntax), 'Fix the path or supply the correct tsconfig alias.')); return; }
+        const targetFile = canonical(target); files.add(targetFile);
+        if (/(?:^|\/)server(?:\/|$)|\.server\.[cm]?[jt]s$/.test(targetFile)) diagnostics.push(diagnostic('HESH-SEC-001', `Server-only module in client graph: ${specifier.text}`, file, source, specifier.getStart(syntax), 'Move server calls behind a server API; never import server-only code into the browser.'));
+        const targetDomain = owner(targetFile), sourceDomain = owner(file);
+        if (targetDomain && targetDomain !== sourceDomain) diagnostics.push(diagnostic('HESH-ARCH-004', `Illegal cross-domain dependency. Source domain: ${sourceDomain?.node.name ?? 'shared/application'}. Target domain: ${targetDomain.node.name}. The imported module is private.`, file, source, specifier.getStart(syntax), `Use an explicitly exposed ${targetDomain.node.name} operation through declared dependency injection.`));
+      };
+      const walk = (node: ts.Node): void => {
+        if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) checkImport(node.moduleSpecifier);
+        else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) checkImport(node.argument.literal);
+        else if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(node.expression) && node.expression.text === 'require'))) checkImport(node.arguments[0]);
+        ts.forEachChild(node, walk);
+      };
+      walk(syntax);
+    }
+    for (const failure of [...program.getSyntacticDiagnostics(), ...program.getSemanticDiagnostics()]) if (failure.file && inside(canonical(failure.file.fileName), root)) diagnostics.push(diagnostic('HESH-TYPE-001', ts.flattenDiagnosticMessageText(failure.messageText, '\n'), failure.file.fileName, failure.file.text, failure.start ?? 0, 'Correct the implementation type/syntax error.'));
+    const schemas: Record<string, Record<string, string>> = Object.create(null), urls = new Map<string, Located>();
+    const graph: ProjectResult['graph'] = { domains: domains.map(d => ({ name: d.node.name, exposes: list(d, 'exposes').map(e => e.name), consumes: list(d, 'consumes').map(e => e.name) })), destinations: [], links: [] };
+    const presentationFor = new Map<Located, Located>();
+    for (const item of destinations) {
+      const url = field(item, 'url'), inputs = Object.fromEntries(list(item, 'input', true).map(e => [e.name, e.value ?? '']));
+      const segments = url.split('/').filter(Boolean), params = segments.filter(p => p.startsWith(':')).map(p => p.slice(1));
+      if (!url.startsWith('/') || url.startsWith('//') || /[?#*%]/.test(url) || new Set(params).size !== params.length || params.some(p => !Object.hasOwn(inputs, p)) || Object.keys(inputs).some(p => !params.includes(p))) error('HESH-NAV-003', `URL/input mismatch for ${item.node.name}`, item, item.node.start, 'Use an absolute URL whose :params exactly match the input block; use plain static segments.');
+      for (const input of list(item, 'input')) if (!['string', 'number', 'boolean'].includes(input.value ?? '') || input.name.includes('.')) error('HESH-NAV-003', `Invalid input schema ${input.name}`, item, input.start);
+      for (const key of Object.keys(inputs)) if (!/^[A-Za-z_][A-Za-z\d_]*$/.test(key)) error('HESH-NAV-003', `Unsupported URL parameter name ${key}`, item, item.node.start, 'Use ASCII letters/digits/underscore with a letter or underscore first.');
+      if (new Set(Object.keys(inputs).map(key => key.toLowerCase())).size !== Object.keys(inputs).length) error('HESH-NAV-003', 'Destination input names must be unique ignoring case for HTML attributes', item);
+      const signature = segments.map(p => p.startsWith(':') ? ':' : p).join('/');
+      if (urls.has(signature)) error('HESH-NAV-004', `Conflicting destination URL ${url}`, item); else urls.set(signature, item);
+      for (const previous of destinations.slice(0, destinations.indexOf(item))) {
+        const other = (previous.node.fields.url?.value ?? '').split('/').filter(Boolean);
+        if (other.length === segments.length && other.every((part, index) => part === segments[index] || part.startsWith(':') || segments[index]!.startsWith(':'))) error('HESH-NAV-004', `Overlapping destination URLs: ${url} and ${previous.node.fields.url?.value}`, item, item.node.start, 'Use non-overlapping addresses so destination input always resolves to the declared screen.');
+      }
+      const presentation = declarations.get(field(item, 'presentation'));
+      if (!presentation || presentation.node.kind !== 'presentation') error('HESH-NAV-001', `Missing presentation for ${item.node.name}`, item);
+      else {
+        const own = owner(presentation.file);
+        if (!own || !byDomain.has(own.node.name) || owner(item.file) !== own) error('HESH-ARCH-004', 'Destination and presentation must belong to the same selected domain', item);
+        else { presentationFor.set(item, presentation); graph.destinations.push({ name: item.node.name, url, input: inputs, owner: own.node.name }); }
+      }
+      schemas[item.node.name] = inputs;
+    }
+    const outputs: Record<string, string> = {}, htmlModules = new Map<Located, string>();
+    for (const item of new Set(presentationFor.values())) {
+      const html = canonical(resolve(dirname(item.file), field(item, 'html'))), stylePath = field(item, 'styles', false);
+      if (!isFile(html) || !html.endsWith('.html') || !inside(html, canonical(dirname(item.file)))) { error('HESH-HTML-001', `Missing or private presentation HTML ${html}`, item); continue; }
+      const source = read(html), factory = resolvedFactories.get(item);
+      const compiled = compileHTML(source, { filename: html, bindings: list(item, 'bindings', true).map(e => e.name), actions: list(item, 'actions', true).map(e => e.name), destinations: schemas,
+        validateBinding(path, offset, expected, writable) {
+          if (!factory) return;
+          const type = getMember(factory.result, ['bindings', ...path.split('.')], true);
+          if (type && type.flags & ts.TypeFlags.Any) diagnostics.push(diagnostic('HESH-TYPE-002', `Binding ${path} has a dynamic any type; its nested shape/input type cannot be proven`, html, source, offset, 'Add JSDoc or a TypeScript type if static checking is required; runtime destination validation still applies.', 'warning'));
+          if (!type) diagnostics.push(diagnostic('HESH-BIND-002', `Missing nested data path ${path}`, html, source, offset, 'Return this field in the declared bindings.'));
+          if (writable) {
+            const raw = getMember(factory.result, ['bindings', path]);
+            if (!raw || !checker.getPropertyOfType(raw, 'set')) diagnostics.push(diagnostic('HESH-BIND-004', `Binding ${path} is not writable`, html, source, offset, 'Use a writable signal for h-value.'));
+          }
+          if (expected && type && !(type.flags & ts.TypeFlags.Any)) {
+            const actual = type.flags & ts.TypeFlags.StringLike ? 'string' : type.flags & ts.TypeFlags.NumberLike ? 'number' : type.flags & ts.TypeFlags.BooleanLike ? 'boolean' : 'object/unknown';
+            if (actual !== expected) diagnostics.push(diagnostic('HESH-NAV-003', `Destination binding ${path} is ${actual}, expected ${expected}`, html, source, offset, 'Bind a value of the destination input type.'));
+          }
+        }
+      });
+      diagnostics.push(...compiled.diagnostics);
+      for (const [destination, screen] of presentationFor) if (screen === item) for (const target of compiled.destinations) graph.links.push({ from: destination.node.name, to: target });
+      const output = join(outDir, `${item.node.name}.js`); htmlModules.set(item, output);
+      let css = '';
+      if (stylePath) {
+        const style = canonical(resolve(dirname(item.file), stylePath));
+        if (!isFile(style) || !style.endsWith('.css') || !inside(style, canonical(dirname(item.file)))) error('HESH-HTML-001', `Missing/private CSS resource ${stylePath}`, item);
+        else { files.add(style); css = `import ${JSON.stringify(modulePath(output, style))};\n`; }
+      }
+      outputs[output] = css + compiled.code;
+    }
+    const output = join(outDir, 'app.js'), types = join(outDir, 'app.d.ts');
+    const js = ["import { createGraphApplication, createDomainGraph } from '@heshammesalam/heshjs/destinations';"];
+    const domainValues: string[] = [], pageValues: string[] = [], typeImports: string[] = [], domainTypes: string[] = [];
+    let index = 0;
+    for (const item of domains) {
+      const factory = resolvedFactories.get(item); if (!factory) continue;
+      const alias = `factory${index++}`, spec = modulePath(output, factory.file);
+      js.push(`import { ${factory.name} as ${alias} } from ${JSON.stringify(spec)};`);
+      typeImports.push(`import { ${factory.name} as ${alias} } from ${JSON.stringify(spec)};`);
+      const operations = list(item, 'exposes').map(e => e.name);
+      domainValues.push(`{name:${JSON.stringify(item.node.name)}, factory:${alias}, exposes:${JSON.stringify(operations)}, consumes:${JSON.stringify(list(item, 'consumes').map(e => e.name))}, access:${JSON.stringify(Object.fromEntries(list(item, 'access').map(e => [e.name, e.value])))}}`);
+      const tree: Record<string, unknown> = {};
+      for (const operation of operations) { let node = tree; const parts = operation.split('.'); parts.forEach((part, i) => { if (i === parts.length - 1) node[part] = `ReturnType<typeof ${alias}>${parts.map(p => `[${JSON.stringify(p)}]`).join('')}`; else node = (node[part] ??= {}) as Record<string, unknown>; }); }
+      const typeTree = (value: Record<string, unknown>): string => '{' + Object.entries(value).map(([key, value]) => `readonly ${JSON.stringify(key)}:${typeof value === 'string' ? value : typeTree(value as Record<string, unknown>)}`).join(';') + '}';
+      domainTypes.push(`${JSON.stringify(item.node.name)}:${typeTree(tree)}`);
+    }
+    for (const item of destinations) {
+      const presentation = presentationFor.get(item), factory = presentation && resolvedFactories.get(presentation), html = presentation && htmlModules.get(presentation);
+      const data = graph.destinations.find(d => d.name === item.node.name);
+      if (!presentation || !factory || !html || !data) continue;
+      pageValues.push(`{...${JSON.stringify({ ...data, access: item.node.fields.access?.value })}, load:async()=>{const [logic,template]=await Promise.all([import(${JSON.stringify(modulePath(output, factory.file))}),import(${JSON.stringify(modulePath(output, html))})]);return {create:logic[${JSON.stringify(factory.name)}],view:template.default};}}`);
+    }
+    js.push(`const domains = [${domainValues.join(',\n')}];`, `const pages = [${pageValues.join(',\n')}];`, 'export const metadata = ' + JSON.stringify(graph) + ';', 'export const createDomains = (options = {}) => createDomainGraph(domains, options);', 'export const createApplication = (options = {}) => createGraphApplication(domains, pages, options);');
+    const destinationTypes = graph.destinations.map(d => `${JSON.stringify(d.name)}: Destination<${Object.keys(d.input).length ? '{' + Object.entries(d.input).map(([key, type]) => `${JSON.stringify(key)}:${type}`).join(';') + '}' : 'Record<string, never>'}>`);
+    outputs[output] = js.join('\n');
+    outputs[types] = ["import type { Destination, GraphApplication, ApplicationOptions, DomainGraph } from '@heshammesalam/heshjs/destinations';", ...typeImports, `export interface DomainAPIs {${domainTypes.join(';')}}`, `export interface Destinations {${destinationTypes.join(';')}}`, 'export declare function createDomains(options?: ApplicationOptions): DomainGraph<DomainAPIs>;', 'export declare function createApplication(options?: ApplicationOptions): GraphApplication<Destinations, DomainAPIs>;', 'export declare const metadata: unknown;'].join('\n');
+    if (diagnostics.some(d => d.severity === 'error')) for (const name of Object.keys(outputs)) delete outputs[name];
+    return { diagnostics, files: [...files].sort(), outputs, graph, statistics: { parsed, reused } };
+  } };
+}
+export function checkProject(options: ProjectOptions): ProjectResult { return createArchitectureCompiler().check(options); }
+export function writeProject(result: ProjectResult): void {
+  if (result.diagnostics.some(d => d.severity === 'error')) throw new Error(result.diagnostics.map(formatDiagnostic).join('\n'));
+  for (const [file, source] of Object.entries(result.outputs)) { mkdirSync(dirname(file), { recursive: true }); if (!existsSync(file) || readFileSync(file, 'utf8') !== source) writeFileSync(file, source); }
+}

package/src/compiler/index.ts

@@ -11,6 +11,7 @@ const f = ts.factory;
 
 export function compile(source: string, options: CompileOptions = {}): Result {
   const ast = parse(source, options.filename);
+  if (ast.contracts.length) throw new HeshError('Architecture declarations require the project compiler (hesh check or hesh({ architecture: ... }))', source, ast.contracts[0]!.start, ast.filename);
   const metadata: Binding[] = [];
   const fail = (message: string, offset: number): never => { throw new HeshError(message, source, offset, ast.filename); };
   const names = new Set<string>();

package/src/destinations/index.ts

@@ -0,0 +1,146 @@
+import { createRouter } from '../router/index.js';
+import { defineModule, useController, type RouteLocation } from '../hmvc/index.js';
+import { createDomainGraph, ClientPolicyDenied, type DomainDefinition, type DomainOptions, type DomainGraph } from '../domains/index.js';
+import { signal, effect, onCleanup, scope, type Disposer } from '../reactivity/index.js';
+import { mount, element, text } from '../dom/index.js';
+import type { PresentationState } from '../presentation/index.js';
+export type InputType = 'string' | 'number' | 'boolean';
+export interface TransitionOptions { query?: Record<string, string>; hash?: string; presentation?: 'page' }
+export interface Destination<I extends object> {
+  readonly name: string;
+  href(input: I, options?: TransitionOptions): string;
+  open(input: I, options?: TransitionOptions): void;
+  replace(input: I, options?: TransitionOptions): void;
+  /** Prefetch code/resources, not business data or authorization results. */
+  prefetch(input: I): Promise<void>;
+}
+export interface PresentationContext {
+  domains: Record<string, unknown>;
+  input: Record<string, string | number | boolean>;
+  location: RouteLocation;
+  signal: AbortSignal;
+}
+export interface PresentationResources {
+  create(context: PresentationContext): PresentationState;
+  view(parent: Node, state: PresentationState, destinations: Record<string, Destination<Record<string, unknown>>>): void;
+}
+export interface DestinationDefinition {
+  name: string; url: string; input: Record<string, InputType>; owner: string; access?: string;
+  load(): Promise<PresentationResources>;
+}
+export interface DestinationEvent { type: 'loading' | 'ready' | 'blocked' | 'error' | 'cancelled' | 'disposed'; destination: string; reason?: string }
+export interface ApplicationOptions extends DomainOptions { window?: Window; onError?: (error: unknown) => void; onDiagnostic?: (event: DestinationEvent) => void }
+export interface GraphApplication<D = Record<string, Destination<Record<string, unknown>>>, G = Record<string, Record<string, unknown>>> {
+  destinations: D;
+  domains: G;
+  status: { get(): { phase: 'idle' | 'loading' | 'ready' | 'error'; destination?: string; error?: unknown } };
+  start(parent: Node): Disposer;
+  stop(): void;
+}
+export function validateInput(schema: Record<string, InputType>, input: object): Record<string, string | number | boolean> {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Destination input must be an object');
+  const values = input as Record<string, unknown>;
+  for (const key of Object.keys(values)) if (!Object.hasOwn(schema, key)) throw new Error(`Unknown destination input ${key}`);
+  const result: Record<string, string | number | boolean> = Object.create(null);
+  for (const [key, type] of Object.entries(schema)) {
+    const value = values[key];
+    if (!Object.hasOwn(values, key) || typeof value !== type || (type === 'number' && !Number.isFinite(value)) || (type === 'string' && !(value as string).length)) throw new Error(`Destination input ${key} must be ${type}${type === 'string' ? ' (nonempty)' : ''}`);
+    if (type === 'string' && (value === '.' || value === '..')) throw new Error(`Destination input ${key} cannot be a URL dot segment`);
+    result[key] = value as string | number | boolean;
+  }
+  return result;
+}
+function decodeInput(definition: DestinationDefinition, params: Readonly<Record<string, string>>): Record<string, string | number | boolean> {
+  const values: Record<string, unknown> = Object.create(null);
+  for (const [key, type] of Object.entries(definition.input)) {
+    const raw = params[key];
+    if (raw === undefined) throw new Error(`Missing URL input ${key}`);
+    if (type === 'boolean' && raw !== 'true' && raw !== 'false') throw new Error(`URL input ${key} must be true/false`);
+    if (type === 'number' && !raw.trim()) throw new Error(`URL input ${key} must be numeric`);
+    values[key] = type === 'number' ? Number(raw) : type === 'boolean' ? raw === 'true' : raw;
+  }
+  return validateInput(definition.input, values);
+}
+export function createGraphApplication(definitions: readonly DomainDefinition[], pages: readonly DestinationDefinition[], options: ApplicationOptions = {}): GraphApplication {
+  const graph = createDomainGraph(definitions, options);
+  const status = signal<{ phase: 'idle' | 'loading' | 'ready' | 'error'; destination?: string; error?: unknown }>({ phase: 'idle' });
+  const report = options.onError ?? (error => console.error(error));
+  const emit = (type: DestinationEvent['type'], destination: string, error?: unknown) => {
+    if (!options.onDiagnostic) return;
+    try { options.onDiagnostic({ type, destination, ...(error === undefined ? {} : { reason: error instanceof Error ? error.message : String(error) }) }); }
+    catch (failure) { report(failure); }
+  };
+  const destinations: Record<string, Destination<Record<string, unknown>>> = Object.create(null);
+  const code = new Map<string, Promise<PresentationResources>>();
+  let stopped = false;
+  const load = (page: DestinationDefinition) => {
+    let result = code.get(page.name);
+    if (!result) { result = Promise.resolve().then(page.load).catch(error => { code.delete(page.name); throw error; }); code.set(page.name, result); }
+    return result;
+  };
+  const authorize = (page: DestinationDefinition) => {
+    if (page.access && options.authorize?.(page.access) !== true) throw new ClientPolicyDenied(page.access, page.name);
+  };
+  const routes = pages.map(page => ({ path: page.url, module: defineModule({
+    model: context => context.route,
+    controller: route => route,
+    view(parent) {
+      const route = useController<{ get(): RouteLocation }>();
+      effect(() => {
+        const location = route.get();
+        const abort = new AbortController(); let dispose: Disposer | undefined, settled = false;
+        onCleanup(() => { abort.abort(); dispose?.(); emit(settled ? 'disposed' : 'cancelled', page.name); });
+        const message = element(parent, 'p'); message.setAttribute('role', 'status'); text(message, () => 'Loading…');
+        status.set({ phase: 'loading', destination: page.name });
+        emit('loading', page.name);
+        const failed = (error: unknown) => {
+          if (abort.signal.aborted) return;
+          settled = true;
+          message.textContent = 'Unable to open this destination.'; message.setAttribute('role', 'alert');
+          status.set({ phase: 'error', destination: page.name, error }); emit(error instanceof ClientPolicyDenied ? 'blocked' : 'error', page.name, error); report(error);
+        };
+        let input: ReturnType<typeof validateInput>;
+        try { authorize(page); input = decodeInput(page, location.params); } catch (error) { failed(error); return; }
+        void load(page).then(resources => {
+          if (abort.signal.aborted) return;
+          const owned = scope(() => {
+            const state = resources.create({ input, domains: graph.forDomain(page.owner), location, signal: abort.signal });
+            if (state && typeof (state as unknown as { then?: unknown }).then === 'function') throw new Error('Presentation factories must be synchronous; use the provided AbortSignal for async work');
+            mount(() => resources.view(parent, state, destinations), parent, { onError: report });
+          });
+          dispose = owned.dispose;
+          if (abort.signal.aborted) { dispose(); return; }
+          settled = true; message.remove(); status.set({ phase: 'ready', destination: page.name }); emit('ready', page.name);
+          // Page-only focus management; opt-in target or the first heading.
+          const target = (parent as Element).querySelector?.('[data-hesh-focus], h1, h2') as HTMLElement | null | undefined;
+          if (target) { if (!target.hasAttribute('tabindex')) target.setAttribute('tabindex', '-1'); target.focus({ preventScroll: true }); }
+        }).catch(failed);
+      });
+    }
+  }) }));
+  let router: ReturnType<typeof createRouter>;
+  try { router = createRouter({ routes, window: options.window, onError: report }); }
+  catch (error) { graph.dispose(); throw error; }
+  for (const page of pages) {
+    if (destinations[page.name]) { graph.dispose(); throw new Error(`Duplicate destination ${page.name}`); }
+    const href = (input: object, transition: TransitionOptions = {}) => {
+      if (stopped) throw new Error('Application is disposed');
+      if (transition.presentation && transition.presentation !== 'page') throw new Error('Only page presentation is supported');
+      const values = validateInput(page.input, input);
+      const path = page.url.split('/').map(part => part.startsWith(':') ? encodeURIComponent(String(values[part.slice(1)])) : part).join('/');
+      const query = new URLSearchParams(transition.query).toString();
+      const hash = transition.hash ? '#' + encodeURIComponent(transition.hash) : '';
+      return path + (query ? '?' + query : '') + hash;
+    };
+    destinations[page.name] = Object.freeze({ name: page.name, href,
+      open(input: object, transition?: TransitionOptions) { authorize(page); router.navigate(href(input, transition)); },
+      replace(input: object, transition?: TransitionOptions) { authorize(page); router.navigate(href(input, transition), { replace: true }); },
+      async prefetch(input: object) { href(input); await load(page); }
+    });
+  }
+  const stop = () => { if (stopped) return; stopped = true; try { router.stop(); } finally { try { graph.dispose(); } finally { code.clear(); status.set({ phase: 'idle' }); } } };
+  return { destinations: Object.freeze(destinations), domains: graph.domains, status: { get: status.get },
+    start(parent) { if (stopped) throw new Error('Application is disposed'); try { router.start(parent); return stop; } catch (error) { stop(); throw error; } }, stop };
+}
+export { createDomainGraph };
+export type { DomainDefinition, DomainGraph };

package/src/dom/index.ts

@@ -12,7 +12,12 @@ export function mount(component: Component, parent: Node, options: MountOptions
 }
 
 export function element(parent: Node, name: string): HTMLElement {
-  const node = parent.ownerDocument!.createElement(aliases[name] ?? name);
+  return nativeElement(parent, aliases[name] ?? name);
+}
+
+/** Creates the exact HTML tag name, without Hesh shorthand aliases. */
+export function nativeElement(parent: Node, name: string): HTMLElement {
+  const node = parent.ownerDocument!.createElement(name);
   parent.appendChild(node);
   onCleanup(() => node.remove());
   return node;

package/src/domains/index.ts

@@ -0,0 +1,97 @@
+import { scope, type Disposer } from '../reactivity/index.js';
+export interface DomainDefinition {
+  name: string;
+  exposes: readonly string[];
+  consumes: readonly string[];
+  access?: Readonly<Record<string, string>>;
+  factory: (dependencies: Record<string, Record<string, unknown>>) => unknown;
+}
+export interface DomainOptions { authorize?: (policy: string) => boolean }
+export class ClientPolicyDenied extends Error {
+  readonly code = 'HESH-ACCESS-001';
+  constructor(readonly policy: string, readonly contract: string) {
+    super(`Client policy denied: ${policy} (${contract}). Server authorization is still required.`);
+  }
+}
+export interface DomainGraph<T = Record<string, Record<string, unknown>>> {
+  readonly domains: T;
+  forDomain(name: string): Record<string, unknown>;
+  dispose: Disposer;
+}
+const unsafe = new Set(['__proto__', 'constructor', 'prototype']);
+export function contractPath(path: string): string[] {
+  const parts = path.split('.');
+  if (parts.some(p => !p || unsafe.has(p))) throw new Error(`Invalid contract path ${path}`);
+  return parts;
+}
+function project(target: Record<string, unknown>, path: string[], value: unknown): void {
+  const name = path[0]!;
+  if (path.length === 1) { target[name] = value; return; }
+  if (target[name] !== undefined && (typeof target[name] !== 'object' || target[name] === null)) throw new Error(`Overlapping public contracts at ${name}`);
+  const next = (target[name] ??= Object.create(null)) as Record<string, unknown>;
+  project(next, path.slice(1), value);
+}
+function freeze(value: Record<string, unknown>): Record<string, unknown> {
+  for (const child of Object.values(value)) if (child && typeof child === 'object') freeze(child as Record<string, unknown>);
+  return Object.freeze(value);
+}
+function lookup(value: unknown, parts: string[]): { value: unknown; receiver: unknown } {
+  let receiver: unknown;
+  for (const part of parts) {
+    receiver = value;
+    value = value != null && Object.hasOwn(Object(value), part) ? (value as Record<string, unknown>)[part] : undefined;
+  }
+  return { value, receiver };
+}
+export function createDomainGraph(definitions: readonly DomainDefinition[], options: DomainOptions = {}): DomainGraph {
+  const byName = new Map(definitions.map(d => [d.name, d]));
+  if (byName.size !== definitions.length) throw new Error('Duplicate domain name');
+  const domains: Record<string, Record<string, unknown>> = Object.create(null);
+  const contexts: Record<string, Record<string, unknown>> = Object.create(null);
+  const building = new Set<string>();
+  let disposed = false;
+  const owned = scope(() => {
+    const build = (name: string): Record<string, unknown> => {
+      if (domains[name]) return domains[name]!;
+      const definition = byName.get(name);
+      if (!definition) throw new Error(`Missing domain ${name}`);
+      if (building.has(name)) throw new Error(`Circular domain dependency at ${name}`);
+      building.add(name);
+      const dependencies: Record<string, Record<string, unknown>> = Object.create(null);
+      for (const dependency of definition.consumes) {
+        const [provider, ...operation] = contractPath(dependency);
+        if (!operation.length) throw new Error(`Dependency must name an operation: ${dependency}`);
+        const target = build(provider!);
+        const value = lookup(target, operation).value;
+        if (typeof value !== 'function') throw new Error(`Missing public operation ${dependency}`);
+        project(dependencies[provider!] ??= Object.create(null), operation, value);
+      }
+      freeze(dependencies);
+      const implementation = definition.factory(dependencies);
+      if (implementation && typeof (implementation as { then?: unknown }).then === 'function') throw new Error(`Domain ${name} factory must be synchronous`);
+      const facade: Record<string, unknown> = Object.create(null);
+      for (const operation of definition.exposes) {
+        const parts = contractPath(operation);
+        const { value, receiver } = lookup(implementation, parts);
+        if (typeof value !== 'function') throw new Error(`Unresolved implementation ${name}.${operation}`);
+        project(facade, parts, (...args: unknown[]) => {
+          if (disposed) throw new Error('Domain graph is disposed');
+          const policy = definition.access?.[operation];
+          if (policy && options.authorize?.(policy) !== true) throw new ClientPolicyDenied(policy, `${name}.${operation}`);
+          return Reflect.apply(value, receiver, args);
+        });
+      }
+      domains[name] = freeze(facade);
+      contexts[name] = Object.freeze({ ...dependencies, [name]: domains[name] });
+      building.delete(name);
+      return domains[name]!;
+    };
+    for (const definition of definitions) build(definition.name);
+    freeze(domains);
+  });
+  return {
+    domains,
+    forDomain(name) { if (disposed) throw new Error('Domain graph is disposed'); if (!contexts[name]) throw new Error(`Unknown domain context ${name}`); return contexts[name]!; },
+    dispose() { if (disposed) return; disposed = true; owned.dispose(); }
+  };
+}