@cratis/scene.engine 4.12.0 → 4.13.0

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