@cratis/scene.engine 4.11.0 → 4.13.0

package/navigation/diagnoseNavigation.ts

@@ -0,0 +1,136 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DestinationKind, DestinationReference, Screen } from '@cratis/scene.model';
+import { collectOutlets } from './collectOutlets';
+import { findHostingCycles } from './findHostingCycles';
+import { NavigationDiagnostic } from './NavigationDiagnostic';
+import { NavigationDiagnosticCode } from './NavigationDiagnosticCode';
+import { NavigationGraph } from './NavigationGraph';
+import { NavigationRouteKey, authoredRouteKey, navigationTarget } from './navigationRoute';
+import { OutletOwner } from './OutletOwner';
+
+/**
+ * Diagnoses how destinations, outlets, routes and targets fit together: duplicate routes, duplicate,
+ * missing or incompatible outlets, hosting cycles and unavailable targets.
+ *
+ * Routes are compared by `routeKey` - by default the authored route override, since the engine constructs no
+ * URLs. Nothing is rewritten. The C# engine (`NavigationDiagnostics.Diagnose`) reports the same codes and
+ * messages in the same order for the same model; both are asserted against `navigation-diagnostic-fixtures.json`.
+ */
+export function diagnoseNavigation(graph: NavigationGraph, routeKey: NavigationRouteKey = authoredRouteKey): NavigationDiagnostic[] {
+    const diagnostics: NavigationDiagnostic[] = [];
+    const outlets = collectOutlets(graph, diagnostics);
+    const screens = graph.screens ? new Map(graph.screens.map(screen => [screen.name, screen])) : undefined;
+    const routes = new Map<string, { entry: string; target: string }>();
+    const hostedIn = new Map<string, string[]>();
+
+    graph.entries.forEach((navigationEntry, index) => {
+        const entry = navigationEntry.id ?? `#${index + 1}`;
+        const destination = navigationEntry.destination;
+        const kind = destination.kind ?? (destination.dialog ? DestinationKind.Dialog : DestinationKind.Outlet);
+        const report = (code: NavigationDiagnosticCode, message: string) => diagnostics.push({ code, message, entry });
+
+        if (!destination.screen && !destination.module && !destination.route && !destination.dialog) {
+            report(NavigationDiagnosticCode.UnavailableTarget, `Destination '${entry}' names no screen, stable identity, route or dialog.`);
+            return;
+        }
+
+        diagnoseTarget(graph, screens, destination, kind, entry, report);
+        const owner = diagnoseOutlet(graph, outlets, screens, destination, kind, entry, report);
+        if (owner?.ownerKind === 'ScreenTemplate' && destination.screen && screens?.has(destination.screen)) {
+            const hosts = graph.screens!.filter(screen => screen.screenTemplate === owner.owner).map(screen => screen.name);
+            hostedIn.set(destination.screen, [...new Set([...(hostedIn.get(destination.screen) ?? []), ...hosts])]);
+        }
+
+        const route = kind === DestinationKind.External ? undefined : routeKey(destination);
+        if (route) {
+            const target = navigationTarget(destination, kind);
+            const existing = routes.get(route);
+            if (!existing) {
+                routes.set(route, { entry, target });
+            } else if (existing.target !== target) {
+                report(NavigationDiagnosticCode.DuplicateRoute, `Route '${destination.route ?? route}' is used by destinations '${existing.entry}' and '${entry}', which open different targets.`);
+            }
+        }
+    });
+
+    for (const cycle of findHostingCycles(graph.screens?.map(screen => screen.name) ?? [], hostedIn)) {
+        diagnostics.push({
+            code: NavigationDiagnosticCode.NavigationCycle,
+            message: `Navigation cycle ${[...cycle, cycle[0]].join(' -> ')}: each screen is placed in an outlet owned by the next, so composition never terminates.`,
+        });
+    }
+
+    return diagnostics;
+}
+
+type Report = (code: NavigationDiagnosticCode, message: string) => void;
+
+function diagnoseTarget(
+    graph: NavigationGraph,
+    screens: Map<string, Screen> | undefined,
+    destination: DestinationReference,
+    kind: DestinationKind,
+    entry: string,
+    report: Report,
+) {
+    if (kind === DestinationKind.Dialog) {
+        if (!destination.dialog) {
+            report(NavigationDiagnosticCode.UnavailableTarget, `Dialog destination '${entry}' names no dialog.`);
+        } else if (graph.dialogTemplates && !graph.dialogTemplates.some(template => template.name === destination.dialog)) {
+            report(NavigationDiagnosticCode.UnavailableTarget, `Destination '${entry}' opens dialog '${destination.dialog}', which no dialog template provides.`);
+        }
+        return;
+    }
+
+    if (kind === DestinationKind.Outlet && destination.screen && screens && !screens.has(destination.screen)) {
+        report(NavigationDiagnosticCode.UnavailableTarget, `Destination '${entry}' opens screen '${destination.screen}', which does not exist.`);
+    }
+}
+
+function diagnoseOutlet(
+    graph: NavigationGraph,
+    outlets: Map<string, OutletOwner>,
+    screens: Map<string, Screen> | undefined,
+    destination: DestinationReference,
+    kind: DestinationKind,
+    entry: string,
+    report: Report,
+): OutletOwner | undefined {
+    if (!destination.outlet) return undefined;
+
+    if (kind !== DestinationKind.Outlet) {
+        const opens = kind === DestinationKind.Dialog ? 'a dialog' : 'an external target';
+        report(NavigationDiagnosticCode.IncompatibleOutlet, `Destination '${entry}' opens ${opens} but names outlet '${destination.outlet}'; only outlet destinations render in outlets.`);
+        return undefined;
+    }
+
+    const owner = outlets.get(destination.outlet);
+    if (!owner) {
+        report(NavigationDiagnosticCode.MissingOutlet, `Destination '${entry}' targets missing outlet '${destination.outlet}'.`);
+        return undefined;
+    }
+
+    const screen = destination.screen ? screens?.get(destination.screen) : undefined;
+    if (!screen) return owner;
+
+    if (owner.ownerKind === 'Layout' && screen.layout !== owner.owner) {
+        report(
+            NavigationDiagnosticCode.IncompatibleOutlet,
+            `Outlet '${owner.outlet.name}' belongs to layout '${owner.owner}', but destination '${entry}' places '${screen.name}', which renders in layout '${screen.layout}'.`,
+        );
+    }
+
+    if (owner.outlet.accepts) {
+        const type = graph.screenTemplates?.find(template => template.name === screen.screenTemplate)?.metadata?.type;
+        if (!type || !owner.outlet.accepts.includes(type)) {
+            report(
+                NavigationDiagnosticCode.IncompatibleOutlet,
+                `Outlet '${owner.outlet.name}' accepts ${owner.outlet.accepts.join(', ')} screens, but destination '${entry}' places '${screen.name}' of type '${type ?? 'untyped'}'.`,
+            );
+        }
+    }
+
+    return owner;
+}

package/navigation/findHostingCycles.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Finds cycles in a "renders inside" graph, where an edge from a screen to another means the first is
+ * placed in an outlet the second one's template owns. Screens are visited in the given order and edges in
+ * insertion order, so the same graph always yields the same cycles in the same order. Each set of screens
+ * is reported once, starting from the screen the walk reached it through.
+ */
+export function findHostingCycles(screens: string[], edges: Map<string, string[]>): string[][] {
+    const state = new Map<string, 'visiting' | 'done'>();
+    const stack: string[] = [];
+    const reported = new Set<string>();
+    const cycles: string[][] = [];
+
+    const visit = (screen: string) => {
+        state.set(screen, 'visiting');
+        stack.push(screen);
+        for (const host of edges.get(screen) ?? []) {
+            const hostState = state.get(host);
+            if (hostState === 'visiting') {
+                const cycle = stack.slice(stack.indexOf(host));
+                const key = [...cycle].sort().join('\u0000');
+                if (!reported.has(key)) {
+                    reported.add(key);
+                    cycles.push(cycle);
+                }
+            } else if (hostState === undefined) {
+                visit(host);
+            }
+        }
+        stack.pop();
+        state.set(screen, 'done');
+    };
+
+    for (const screen of screens) {
+        if (!state.has(screen)) visit(screen);
+    }
+
+    return cycles;
+}

package/navigation/index.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './NavigationDiagnostic';
+export * from './NavigationDiagnosticCode';
+export * from './NavigationEntry';
+export * from './NavigationGraph';
+export * from './diagnoseNavigation';
+export * from './navigationEntriesFrom';
+export * from './navigationRoute';

package/navigation/navigationEntriesFrom.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NavigationItem } from '@cratis/scene.model';
+import { NavigationEntry } from './NavigationEntry';
+
+/**
+ * Turns navigation contributions into entries for {@link diagnoseNavigation}. A legacy item carrying only
+ * `targetScreen` becomes a destination for that screen, so old and new content are checked the same way.
+ */
+export function navigationEntriesFrom(items: NavigationItem[]): NavigationEntry[] {
+    return items.map(item => ({
+        id: item.id,
+        destination: item.destination ?? { screen: item.targetScreen, routeParameterBindings: item.routeParameterBindings },
+    }));
+}

package/navigation/navigationRoute.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DestinationReference } from '@cratis/scene.model';
+
+/**
+ * Decides which route a destination occupies, so destinations occupying the same one can be compared.
+ *
+ * The engine constructs no URLs (ADR-004), so it only compares what was authored. A renderer that derives
+ * routes from stable identities, or treats parameter spellings as equivalent, supplies its own key - the same
+ * derivation it uses when it builds the URL - and gets duplicate routes diagnosed by that rule instead.
+ */
+export type NavigationRouteKey = (destination: DestinationReference) => string | undefined;
+
+/** The default route key: the authored route override, trimmed, or none. */
+export const authoredRouteKey: NavigationRouteKey = destination => destination.route?.trim() || undefined;
+
+/**
+ * What a destination opens, so two destinations sharing a route are only a conflict when they open
+ * different things.
+ */
+export function navigationTarget(destination: DestinationReference, kind: string): string {
+    const identity = destination.screen ?? [destination.module, destination.feature, destination.slice].filter(part => part).join('.');
+    return [kind, identity, destination.dialog ?? '', destination.outlet ?? ''].join('|');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.engine",
-    "version": "4.11.0",
+    "version": "4.13.0",
     "description": "The Scene runtime: walks a Scene element tree and drives whichever renderer is plugged in. Does not know React, or any other rendering platform, exists.",
     "keywords": [
         "cratis",
@@ -48,9 +48,9 @@
         "up": "yarn g:up"
     },
     "dependencies": {
-        "@cratis/scene.model": "4.11.0"
+        "@cratis/scene.model": "4.13.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.11.0"
+        "@cratis/scene.model": "4.13.0"
     }
 }

package/packageVersionRange.ts

@@ -42,6 +42,24 @@ export function isVersionSatisfiedBy(version: string, range: string | undefined)
     }
 }
 
+/**
+ * Whether a range is one {@link isVersionSatisfiedBy} understands. An empty range or `*` is valid and means
+ * "any version"; anything the parser cannot read is invalid, so declarations can be rejected up front
+ * instead of surfacing later as a conflict nobody can satisfy.
+ */
+export function isValidVersionRange(range: string | undefined): boolean {
+    const trimmed = range?.trim();
+    if (!trimmed || trimmed === '*') return true;
+    return parseVersion(splitRange(trimmed)[1]) !== undefined;
+}
+
+/**
+ * Whether a value is a `major.minor.patch` version, optionally with a pre-release or build suffix.
+ */
+export function isValidVersion(version: string | undefined): boolean {
+    return version !== undefined && version.trim().length > 0 && parseVersion(version) !== undefined;
+}
+
 type Version = [number, number, number];
 
 function splitRange(range: string): [string, string] {

package/templates/TemplateCatalogEntry.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { TemplateAttribution, TemplateCompatibility, TemplateScope } from '@cratis/scene.model';
+import { TemplateCatalogKind } from './TemplateCatalogKind';
+
+/**
+ * One template as a template browser reads it: what it is, where it comes from, what it needs and whether the
+ * active package set can use it.
+ */
+export interface TemplateCatalogEntry {
+    /** The package that provides the template. */
+    package: string;
+
+    /** The version of that package. */
+    packageVersion: string;
+
+    kind: TemplateCatalogKind;
+    name: string;
+    displayName?: string;
+    description?: string;
+    type?: string;
+    category?: string;
+    scopes?: TemplateScope[];
+    compatibility?: TemplateCompatibility;
+    attribution?: TemplateAttribution;
+    license?: string;
+    licenseUrl?: string;
+
+    /** Whether the template's metadata is complete and every requirement is met. */
+    compatible: boolean;
+
+    /** Why it is not - missing or invalid metadata, or an unmet Scene or package requirement. */
+    problems: string[];
+}

package/templates/TemplateCatalogKind.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Which kind of template a catalog entry describes.
+ */
+export enum TemplateCatalogKind {
+    Layout = 'Layout',
+    ScreenTemplate = 'ScreenTemplate',
+    DialogTemplate = 'DialogTemplate',
+}

package/templates/TemplateSource.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DialogTemplate, Layout, ScenePackage, ScreenTemplate } from '@cratis/scene.model';
+
+/**
+ * A package and the templates it provides. A React `ScenePackageBundle` already has this shape, so hosts pass
+ * their approved bundles straight in.
+ */
+export interface TemplateSource {
+    manifest: ScenePackage;
+    layouts?: Layout[];
+    screenTemplates?: ScreenTemplate[];
+    dialogTemplates?: DialogTemplate[];
+}

package/templates/describeTemplateCatalog.ts

@@ -0,0 +1,92 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ScenePackage, TemplateMetadata } from '@cratis/scene.model';
+import { isVersionSatisfiedBy } from '../packageVersionRange';
+import { TemplateCatalogEntry } from './TemplateCatalogEntry';
+import { TemplateCatalogKind } from './TemplateCatalogKind';
+import { TemplateSource } from './TemplateSource';
+import { validateTemplateMetadata } from './validateTemplateMetadata';
+
+/**
+ * Describes every template the given packages provide, in package then layout, screen template, dialog
+ * template order, with its compatibility, attribution and license metadata and whether it can be used.
+ *
+ * A template is compatible when its metadata is complete and valid, the Scene version (when given) satisfies
+ * its Scene range, and every package it requires is among the given packages at a satisfying version and is
+ * either its own package or one that package depends on. Nothing is filtered out: a browser shows incompatible
+ * templates with their problems rather than hiding why they are unavailable.
+ */
+export function describeTemplateCatalog(sources: TemplateSource[], sceneVersion?: string): TemplateCatalogEntry[] {
+    const versions = new Map(sources.map(source => [source.manifest.name, source.manifest.version]));
+    const entries: TemplateCatalogEntry[] = [];
+
+    for (const source of sources) {
+        const templates = [
+            ...(source.layouts ?? []).map(template => ({ kind: TemplateCatalogKind.Layout, template })),
+            ...(source.screenTemplates ?? []).map(template => ({ kind: TemplateCatalogKind.ScreenTemplate, template })),
+            ...(source.dialogTemplates ?? []).map(template => ({ kind: TemplateCatalogKind.DialogTemplate, template })),
+        ];
+
+        for (const { kind, template } of templates) {
+            const metadata = template.metadata;
+            const describable = template as { displayName?: string; description?: string };
+            const problems = [
+                ...validateTemplateMetadata(template.name, metadata),
+                ...requirementProblems(template.name, metadata, source.manifest, versions, sceneVersion),
+            ];
+
+            entries.push({
+                package: source.manifest.name,
+                packageVersion: source.manifest.version,
+                kind,
+                name: template.name,
+                displayName: describable.displayName,
+                description: describable.description,
+                type: metadata?.type,
+                category: metadata?.category,
+                scopes: metadata?.scopes,
+                compatibility: metadata?.compatibility,
+                attribution: metadata?.attribution,
+                license: metadata?.license,
+                licenseUrl: metadata?.licenseUrl,
+                compatible: problems.length === 0,
+                problems,
+            });
+        }
+    }
+
+    return entries;
+}
+
+function requirementProblems(
+    name: string,
+    metadata: TemplateMetadata | undefined,
+    owner: ScenePackage,
+    versions: Map<string, string>,
+    sceneVersion: string | undefined,
+): string[] {
+    const problems: string[] = [];
+    const compatibility = metadata?.compatibility;
+    if (!compatibility) return problems;
+
+    if (sceneVersion !== undefined && compatibility.scene?.trim() && !isVersionSatisfiedBy(sceneVersion, compatibility.scene)) {
+        problems.push(`Template '${name}' requires Scene ${compatibility.scene} but the host runs ${sceneVersion}`);
+    }
+
+    for (const requirement of compatibility.packages ?? []) {
+        if (!requirement.name?.trim()) continue;
+        if (requirement.name !== owner.name && !owner.dependencies.some(dependency => dependency.name === requirement.name)) {
+            problems.push(`Template '${name}' requires package '${requirement.name}', which its package '${owner.name}' does not depend on`);
+        }
+
+        const version = versions.get(requirement.name);
+        if (version === undefined) {
+            problems.push(`Template '${name}' requires package '${requirement.name}', which is not available`);
+        } else if (!isVersionSatisfiedBy(version, requirement.versionRange)) {
+            problems.push(`Template '${name}' requires package '${requirement.name}' ${requirement.versionRange} but version ${version} is available`);
+        }
+    }
+
+    return problems;
+}

package/templates/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './TemplateCatalogEntry';
+export * from './TemplateCatalogKind';
+export * from './TemplateSource';
+export * from './describeTemplateCatalog';
+export * from './templateMetadataRules';
+export * from './validateTemplateMetadata';

package/templates/templateMetadataRules.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Whether a value is an absolute `https` URL with a host - the only kind of link a template browser
+ * should follow for attribution or license terms. Kept to plain string rules so the C# twin matches exactly.
+ */
+export function isAbsoluteHttpsUrl(value: string): boolean {
+    const prefix = 'https://';
+    return value.startsWith(prefix) && value.length > prefix.length && value[prefix.length] !== '/' && !/\s/.test(value);
+}
+
+/**
+ * Whether a value is a simple SPDX license expression: identifiers such as `MIT`, `Apache-2.0` or
+ * `LicenseRef-Acme`, optionally joined by `AND`, `OR` or `WITH`. Parentheses are not supported.
+ */
+export function isSpdxExpression(value: string): boolean {
+    const tokens = value.split(' ');
+    if (tokens.length % 2 === 0) return false;
+    return tokens.every((token, index) => (index % 2 === 1 ? ['AND', 'OR', 'WITH'].includes(token) : isSpdxIdentifier(token)));
+}
+
+function isSpdxIdentifier(token: string): boolean {
+    return token.length > 0 && [...token].every(character => /[A-Za-z0-9.+-]/.test(character));
+}

package/templates/validateTemplateMetadata.ts

@@ -0,0 +1,55 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { TemplateMetadata } from '@cratis/scene.model';
+import { isValidVersionRange } from '../packageVersionRange';
+import { isAbsoluteHttpsUrl, isSpdxExpression } from './templateMetadataRules';
+
+/**
+ * Checks that a template carries the compatibility, attribution and license metadata every shipped template
+ * needs, and that each value is well formed. The C# engine (`TemplateMetadataValidation.Validate`) reports the
+ * same problems in the same order; both are asserted against `template-metadata-fixtures.json`.
+ */
+export function validateTemplateMetadata(name: string, metadata: TemplateMetadata | undefined): string[] {
+    const problems: string[] = [];
+    const compatibility = metadata?.compatibility;
+
+    if (!compatibility) {
+        problems.push(`Template '${name}' declares no compatibility`);
+    } else {
+        if (!compatibility.scene?.trim()) {
+            problems.push(`Template '${name}' declares no Scene version range`);
+        } else if (!isValidVersionRange(compatibility.scene)) {
+            problems.push(`Template '${name}' declares an invalid Scene version range '${compatibility.scene}'`);
+        }
+
+        for (const requirement of compatibility.packages ?? []) {
+            if (!requirement.name?.trim()) {
+                problems.push(`Template '${name}' declares a package requirement without a name`);
+            } else if (!isValidVersionRange(requirement.versionRange)) {
+                problems.push(`Template '${name}' declares an invalid version range '${requirement.versionRange}' for package '${requirement.name}'`);
+            }
+        }
+    }
+
+    const attribution = metadata?.attribution;
+    if (!attribution?.author?.trim()) {
+        problems.push(`Template '${name}' declares no author`);
+    }
+
+    if (attribution?.url !== undefined && !isAbsoluteHttpsUrl(attribution.url)) {
+        problems.push(`Template '${name}' declares an attribution URL '${attribution.url}' that is not an absolute https URL`);
+    }
+
+    if (!metadata?.license?.trim()) {
+        problems.push(`Template '${name}' declares no license`);
+    } else if (!isSpdxExpression(metadata.license)) {
+        problems.push(`Template '${name}' declares '${metadata.license}', which is not an SPDX license expression`);
+    }
+
+    if (metadata?.licenseUrl !== undefined && !isAbsoluteHttpsUrl(metadata.licenseUrl)) {
+        problems.push(`Template '${name}' declares a license URL '${metadata.licenseUrl}' that is not an absolute https URL`);
+    }
+
+    return problems;
+}

package/validateNavigationDestinations.ts

@@ -1,43 +1,23 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { DestinationReference, Layout, ScreenTemplate } from '@cratis/scene.model';
+import { DestinationReference, DialogTemplate, Layout, Screen, ScreenTemplate } from '@cratis/scene.model';
+import { NavigationDiagnostic, diagnoseNavigation } from './navigation';
 
-export interface NavigationDestinationDiagnostic {
-    code: string;
-    message: string;
-}
+/**
+ * A navigation problem as {@link validateNavigationDestinations} reports it.
+ */
+export type NavigationDestinationDiagnostic = NavigationDiagnostic;
 
 /**
- * Validates destinations against the outlet/route declarations owned by layouts and templates.
+ * Validates destinations against the outlet/route declarations owned by layouts and templates, and - when
+ * the screens and dialog templates are given - against the targets that actually exist.
+ *
+ * A shorthand for {@link diagnoseNavigation} over destinations without entry identities.
  */
 export function validateNavigationDestinations(
     destinations: DestinationReference[],
-    surfaces: { layouts?: Layout[]; screenTemplates?: ScreenTemplate[] } = {},
+    surfaces: { layouts?: Layout[]; screenTemplates?: ScreenTemplate[]; screens?: Screen[]; dialogTemplates?: DialogTemplate[] } = {},
 ): NavigationDestinationDiagnostic[] {
-    const diagnostics: NavigationDestinationDiagnostic[] = [];
-    const outlets = new Set<string>();
-    const routes = new Set<string>();
-
-    for (const surface of [...(surfaces.layouts ?? []), ...(surfaces.screenTemplates ?? [])]) {
-        for (const outlet of surface.outlets ?? []) {
-            if (outlets.has(outlet.name)) diagnostics.push({ code: 'duplicateOutlet', message: `Outlet '${outlet.name}' is declared more than once.` });
-            outlets.add(outlet.name);
-        }
-    }
-
-    for (const destination of destinations) {
-        if (destination.outlet && !outlets.has(destination.outlet)) {
-            diagnostics.push({ code: 'missingOutlet', message: `Destination targets missing outlet '${destination.outlet}'.` });
-        }
-        if (destination.route) {
-            if (routes.has(destination.route)) diagnostics.push({ code: 'duplicateRoute', message: `Route '${destination.route}' is used by more than one destination.` });
-            routes.add(destination.route);
-        }
-        if (!destination.screen && !destination.module && !destination.route && !destination.dialog) {
-            diagnostics.push({ code: 'unavailableTarget', message: 'Destination must name a screen, stable identity, route or dialog.' });
-        }
-    }
-
-    return diagnostics;
+    return diagnoseNavigation({ entries: destinations.map(destination => ({ destination })), ...surfaces });
 }