@heshammesalam/heshjs 0.1.0 → 0.3.0

package/docs/grammar.md

@@ -1,5 +1,9 @@
 # Milestone 1 language (v0.1)
 
+This remains the legacy component grammar. The opt-in architecture descriptor
+extension is specified separately in [contracts.md](contracts.md); it does not
+replace existing .hesh views or add template directives to the brace UI syntax.
+
 The grammar is deliberately smaller than the product roadmap. Source is UTF-8.
 Whitespace and JavaScript comments separate tokens. Identifiers follow JavaScript
 identifier rules. Strings and numbers follow JavaScript lexical rules.

package/docs/hmvc.md

@@ -0,0 +1,134 @@
+# Building an HMVC single-page application
+
+Requires HeshJS 0.2.0. New JavaScript/TypeScript projects use this structure:
+
+```text
+src/
+  main.js                 # starts the router (.ts for TypeScript)
+  app.js                  # explicit route tree
+  modules/
+    shell/
+      model.js
+      controller.js
+      View.hesh
+      Navigation.js
+      module.js
+    home/
+      model.js
+      controller.js
+      View.hesh
+      module.js
+      modules/
+        detail/           # independent nested MVC triad
+          model.js
+          controller.js
+          View.hesh
+          module.js
+    about/                # same MVC structure
+    notFound/             # same MVC structure
+```
+
+This is an application architecture. Compiler, parser and runtime packages stay
+separate infrastructure packages; they are not model/view/controller folders.
+
+## Define a module
+
+```js
+// model.js
+import { signal } from '@heshammesalam/heshjs';
+export const createModel = () => ({ count: signal(0) });
+
+// controller.js
+export const createController = (model, context) => ({
+  count: model.count,
+  increment: () => model.count.set(model.count.get() + 1),
+  id: () => context.route.get().params.id
+});
+```
+
+```hesh
+// View.hesh
+import { useController, Outlet } from '@heshammesalam/heshjs/hmvc';
+export default view Counter {
+  const controller = useController();
+  h1("Count: {controller.count.get()}");
+  button("+", { controller.increment(); });
+  Outlet();
+}
+```
+
+```js
+// module.js
+import { defineModule } from '@heshammesalam/heshjs/hmvc';
+import { createModel } from './model.js';
+import { createController } from './controller.js';
+import View from './View.hesh';
+export const counterModule = defineModule({ model: createModel, controller: createController, view: View });
+```
+
+Factories run once per mounted instance. Use `onCleanup` from HeshJS in factories
+to dispose your subscriptions/resources. Do not call factories at import time if
+their state should be instance-local. `useController`, `useModel` and `useModule`
+are synchronous mount-time accessors. Capture the result in your view; events use
+the captured controller. A controller receives `context.parent` for explicit access
+to the parent module's model/controller. No global store or dependency injection
+container is required. Generic `useController<MyController>()` is available in TS
+view/helper modules, while `.hesh` remains JavaScript without full type checking.
+
+## Declare the route hierarchy
+
+```js
+import { createRouter } from '@heshammesalam/heshjs/router';
+// Import the modules declared by your application.
+export const router = createRouter({ routes: [
+  { path: '/', module: shellModule, children: [
+    { path: '', module: homeModule, children: [
+      { path: 'counter/:id', module: detailModule }
+    ] },
+    { path: 'about', module: aboutModule },
+    { path: '*', module: notFoundModule }
+  ] }
+] });
+
+const dispose = router.start(document.querySelector('#app'));
+router.navigate('/counter/42?from=home');
+router.navigate('/about', { replace: true });
+// dispose() or router.stop() releases all modules and router listeners.
+```
+
+Parents with child routes must render one `Outlet()`. Layout state and DOM stay
+mounted when navigating between their children. Leaving a parent resets its state
+on the next visit. Changes to that module's path parameters recreate the module
+and descendants. Query/hash changes update its reactive `context.route.get()`
+without recreating matching instances. A parent's params contain only parameters
+matched up to that parent; `router.location.get()` contains the deepest match.
+
+Ordinary same-origin anchor clicks update browser history without document reload.
+Use DOM APIs for anchor attributes for now; declarative attribute syntax is not yet
+part of Hesh grammar. The starter's Navigation component is an example. External,
+download, modifier-key and non-self-target links retain browser behavior. Set
+`data-hesh-reload` on an anchor to opt out. Back/forward and initial deep URLs work.
+There is no base-path option yet; deploy at the origin root or define prefixed routes.
+
+Unmatched URLs use `notFound`, a `*` route, or a safe built-in text message.
+`onError` receives navigation/event errors. Programmatic navigation throws errors
+to its caller. Setup must be synchronous. On setup failure new instances are
+disposed, but previously removed children are not restored. Guards, lazy loading,
+async controllers, server authorization and SSR are not implemented.
+
+## Serve deep links in production
+
+Vite dev/preview use SPA fallback. Production hosts must return index.html for
+application paths. The client router cannot fix an HTTP 404 served before JS loads.
+
+For nginx, inside your site's configuration:
+
+```nginx
+location / {
+  try_files $uri $uri/ /index.html;
+}
+```
+
+The scaffold includes `public/_redirects` containing `/* /index.html 200` for hosts
+that support that convention. Configure asset/API routes separately on your host.
+This project does not modify your deployment server automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heshammesalam/heshjs",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "An experimental independent reactive UI framework with brace-based .hesh components",
   "author": "Hesham",
   "license": "UNLICENSED",
@@ -14,11 +14,18 @@
     "./parser": { "types": "./dist/parser/index.d.ts", "import": "./dist/parser/index.js" },
     "./compiler": { "types": "./dist/compiler/index.d.ts", "import": "./dist/compiler/index.js" },
     "./vite": { "types": "./dist/vite/index.d.ts", "import": "./dist/vite/index.js" },
+    "./router": { "types": "./dist/router/index.d.ts", "import": "./dist/router/index.js" },
+    "./hmvc": { "types": "./dist/hmvc/index.d.ts", "import": "./dist/hmvc/index.js" },
+    "./domains": { "types": "./dist/domains/index.d.ts", "import": "./dist/domains/index.js" },
+    "./destinations": { "types": "./dist/destinations/index.d.ts", "import": "./dist/destinations/index.js" },
+    "./presentation": { "types": "./dist/presentation/index.d.ts", "import": "./dist/presentation/index.js" },
+    "./architecture": { "types": "./dist/architecture/index.d.ts", "import": "./dist/architecture/index.js" },
     "./package.json": "./package.json"
   },
-  "files": ["dist", "src", "docs", "README.md"],
+  "files": ["dist", "src", "docs", "README.md", "cli.js"],
+  "bin": { "hesh": "./cli.js" },
   "engines": { "node": ">=22.12.0" },
-  "dependencies": { "typescript": "~5.9.3" },
+  "dependencies": { "typescript": "~5.9.3", "parse5": "8.1.0" },
   "peerDependencies": { "vite": "^7.2.2" },
   "peerDependenciesMeta": { "vite": { "optional": true } },
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }

package/src/architecture/diagnostics.ts

@@ -0,0 +1,11 @@
+export interface ArchitectureDiagnostic {
+  code: string; severity: 'error' | 'warning'; message: string;
+  file: string; offset: number; line: number; column: number; suggestion: string;
+}
+export function diagnostic(code: string, message: string, file: string, source: string, offset: number, suggestion: string, severity: 'error' | 'warning' = 'error'): ArchitectureDiagnostic {
+  const lines = source.slice(0, offset).split('\n');
+  return { code, message, file, offset, line: lines.length, column: lines.at(-1)!.length + 1, suggestion, severity };
+}
+export function formatDiagnostic(item: ArchitectureDiagnostic): string {
+  return `${item.file}:${item.line}:${item.column} ${item.code} ${item.severity}: ${item.message}\n  ${item.suggestion}`;
+}

package/src/architecture/html.ts

@@ -0,0 +1,88 @@
+import { parseFragment, type DefaultTreeAdapterMap } from 'parse5';
+import { diagnostic, type ArchitectureDiagnostic } from './diagnostics.js';
+export interface HTMLContract {
+  filename: string; bindings: string[]; actions: string[];
+  destinations: Record<string, Record<string, string>>;
+  validateBinding?: (path: string, offset: number, expected?: string, writable?: boolean) => void;
+}
+export interface HTMLResult { code: string; diagnostics: ArchitectureDiagnostic[]; usedBindings: string[]; usedActions: string[]; destinations: string[] }
+export function compileHTML(source: string, contract: HTMLContract): HTMLResult {
+  const diagnostics: ArchitectureDiagnostic[] = [], usedBindings = new Set<string>(), usedActions = new Set<string>();
+  const report = (code: string, message: string, at: number, suggestion: string, severity: 'error' | 'warning' = 'error') => diagnostics.push(diagnostic(code, message, contract.filename, source, at, suggestion, severity));
+  const fragment = parseFragment(source, { sourceCodeLocationInfo: true, onParseError: error => report('HESH-HTML-001', error.code, error.startOffset, 'Correct the HTML syntax.') });
+  const lines = ["import * as p from '@heshammesalam/heshjs/presentation';", 'export default function render(parent, state, destinations) {'];
+  let serial = 0;
+  const linked = new Set<string>();
+  const path = (value: string, offset: number, expected?: string, writable = false): string => {
+    const pieces = value.trim().split('.');
+    if (pieces.some(piece => !/^[$_\p{ID_Start}][$_\u200c\u200d\p{ID_Continue}]*$/u.test(piece) || ['constructor', '__proto__', 'prototype'].includes(piece))) report('HESH-BIND-001', `Invalid binding path ${value}`, offset, 'Use a declared dotted data path, not an expression.');
+    if (!contract.bindings.includes(pieces[0]!)) report('HESH-BIND-002', `Missing data binding ${pieces[0]}`, offset, 'Declare the binding and return it from the presentation factory.');
+    usedBindings.add(pieces[0]!); contract.validateBinding?.(value.trim(), offset, expected, writable);
+    return `p.readBinding(state.bindings, ${JSON.stringify(value.trim())})`;
+  };
+  const interpolation = (value: string, offset: number): string => {
+    const parts: string[] = []; let literal = '', cursor = 0;
+    const emit = () => { if (literal) { parts.push(JSON.stringify(literal)); literal = ''; } };
+    while (cursor < value.length) {
+      if (value[cursor] === '\\' && ['{', '}'].includes(value[cursor + 1] ?? '')) { literal += value[cursor + 1]; cursor += 2; continue; }
+      if (value[cursor] !== '{') { literal += value[cursor++]; continue; }
+      emit(); const start = ++cursor, end = value.indexOf('}', start);
+      if (end < 0) { report('HESH-BIND-001', 'Unterminated interpolation', offset + start - 1, 'Close the binding with }.'); break; }
+      parts.push(`String(${path(value.slice(start, end), offset + start)} ?? '')`); cursor = end + 1;
+    }
+    emit(); return parts.join(' + ') || "''";
+  };
+  const visit = (node: DefaultTreeAdapterMap['childNode'], parent: string): void => {
+    const at = node.sourceCodeLocation?.startOffset ?? 0;
+    if (node.nodeName === '#text') { lines.push(`p.text(${parent}, () => ${interpolation((node as DefaultTreeAdapterMap['textNode']).value, at)});`); return; }
+    if (!('tagName' in node)) return;
+    if (node.namespaceURI !== 'http://www.w3.org/1999/xhtml' || ['script', 'iframe', 'object', 'embed', 'base', 'meta', 'link', 'style', 'template'].includes(node.tagName)) {
+      report('HESH-HTML-002', `Unsupported active/foreign template element <${node.tagName}>`, at, 'Use semantic HTML and declared CSS/JS modules.'); return;
+    }
+    const id = `node${serial++}`;
+    lines.push(`const ${id} = p.element(${parent}, ${JSON.stringify(node.tagName)});`);
+    const attributes = Object.fromEntries(node.attrs.map(attr => [attr.name, attr.value]));
+    const attrAt = (name: string) => node.sourceCodeLocation?.attrs?.[name]?.startOffset ?? at;
+    for (const attr of node.attrs) {
+      if (attr.name.startsWith('h-')) continue;
+      if (/^on/i.test(attr.name) || ['srcdoc', 'innerhtml', 'outerhtml'].includes(attr.name)) { report('HESH-HTML-003', `Unsafe attribute ${attr.name}`, attrAt(attr.name), 'Use h-action and safe DOM bindings.'); continue; }
+      const wholeBinding = attr.value.startsWith('{') && attr.value.endsWith('}') && !attr.value.slice(1, -1).includes('{') && !attr.value.slice(1, -1).includes('}');
+      lines.push(`p.attribute(${id}, ${JSON.stringify(attr.name)}, () => ${wholeBinding ? path(attr.value.slice(1, -1), attrAt(attr.name) + 1) : interpolation(attr.value, attrAt(attr.name))});`);
+    }
+    for (const name of Object.keys(attributes)) if (name.startsWith('h-') && !['h-action', 'h-bind', 'h-value', 'h-destination'].includes(name) && !name.startsWith('h-input-')) report('HESH-HTML-004', `Unsupported directive ${name}`, attrAt(name), 'Use supported directives; keyed lists/scoped templates are a later milestone.');
+    if (attributes['h-bind'] !== undefined) {
+      if (node.childNodes.length) report('HESH-BIND-003', 'h-bind cannot also contain children', at, 'Remove the children or use text interpolation.');
+      lines.push(`p.text(${id}, () => ${path(attributes['h-bind'], attrAt('h-bind'))});`);
+    } else node.childNodes.forEach(child => visit(child, id));
+    if (attributes['h-action'] !== undefined) {
+      const name = attributes['h-action']; usedActions.add(name);
+      if (!contract.actions.includes(name)) report('HESH-ACTION-001', `Missing action ${name}`, attrAt('h-action'), 'Declare and implement the action.');
+      lines.push(`p.bindAction(${id}, state, ${JSON.stringify(name)});`);
+    }
+    if (attributes['h-value'] !== undefined) {
+      const name = attributes['h-value'];
+      if (!['input', 'textarea', 'select'].includes(node.tagName) || name.includes('.') || ['checkbox', 'radio', 'file'].includes(attributes.type ?? '') || attributes.multiple !== undefined) report('HESH-BIND-004', 'h-value requires a single-value text control and root writable signal', attrAt('h-value'), 'Use a text input/textarea/single select and a declared signal.');
+      path(name, attrAt('h-value'), undefined, true);
+      lines.push(`p.bindValue(${id}, state.bindings, ${JSON.stringify(name)});`);
+    }
+    const destination = attributes['h-destination'];
+    const inputs = Object.keys(attributes).filter(name => name.startsWith('h-input-'));
+    if (destination !== undefined) {
+      linked.add(destination);
+      const schema = contract.destinations[destination];
+      if (!schema) report('HESH-NAV-001', `Unknown destination ${destination}`, attrAt('h-destination'), 'Declare this destination in the application.');
+      if (node.tagName !== 'a' || attributes.href !== undefined) report('HESH-NAV-002', 'h-destination requires an anchor without an explicit href', at, 'Use <a h-destination="Name" ...>.');
+      for (const key of Object.keys(schema ?? {})) if (attributes[`h-input-${key.toLowerCase()}`] === undefined) report('HESH-NAV-003', `Missing destination input ${key}`, at, `Add h-input-${key} bound to a declared value.`);
+      const entries = inputs.map(attr => {
+        const key = Object.keys(schema ?? {}).find(key => key.toLowerCase() === attr.slice(8)) ?? attr.slice(8);
+        if (!schema || !Object.hasOwn(schema, key)) report('HESH-NAV-003', `Unknown destination input ${key}`, attrAt(attr), 'Use only inputs declared by the destination.');
+        return `${JSON.stringify(key)}: ${path(attributes[attr]!, attrAt(attr), schema?.[key])}`;
+      });
+      lines.push(`p.attribute(${id}, 'href', () => destinations[${JSON.stringify(destination)}].href({${entries.join(',')}}));`);
+    } else if (inputs.length) report('HESH-NAV-003', 'h-input-* requires h-destination', at, 'Declare the destination on this anchor.');
+  };
+  fragment.childNodes.forEach(node => visit(node, 'parent')); lines.push('}');
+  for (const name of contract.bindings) if (!usedBindings.has(name)) report('HESH-BIND-005', `Unused binding ${name}`, 0, 'Remove the declaration if it is not needed by this template.', 'warning');
+  for (const name of contract.actions) if (!usedActions.has(name)) report('HESH-ACTION-002', `Unused action ${name}`, 0, 'Remove the declaration if it is not needed by this template.', 'warning');
+  return { code: lines.join('\n'), diagnostics, usedBindings: [...usedBindings], usedActions: [...usedActions], destinations: [...linked] };
+}

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>();