frameyard 0.7.0 → 0.9.0

package/dist/html/validate.js

@@ -1,12 +1,12 @@
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { KNOWN_DATA_FY_ATTRIBUTES, isAnimationAttribute, isLocalRelative, isMediaAttribute, isRemote, readAnimationDeclarations, readCompositionDescriptor, readMediaDeclarations, readTranscriptDeclarations, } from "../composition/index.js";
-import { mergeProps, } from "../contracts.js";
+import { KNOWN_DATA_FY_ATTRIBUTES, isAnimationAttribute, isLocalRelative, isMediaAttribute, isRemote, readAnimationDeclarations, readCompositionDescriptor, readMediaDeclarations, readTranscriptDeclarations, resolveCompositionMetadata, } from "../composition/index.js";
+import { isPlainObject, mergeProps, } from "../contracts.js";
 import { resolveBindingPath, suggestBindingPath, validateBindingPath } from "../bindings.js";
 import { errorMessage, isFrameyardError } from "../errors.js";
 import { parseTranscript } from "../transcript.js";
 import { createParse5Adapter } from "./document-adapter.js";
-import { findElements, getAttribute, getAttributeLocation, getDocumentDoctype, getElementByTagName, getElementLocation, getNodeLocation, hasAttribute, isDescendantOf, isElement, isTemplate, isTextNode, parseHtml, walk, } from "./parse.js";
+import { findElements, getAttribute, getAttributeLocation, getDocumentDoctype, getElementLocation, getNodeLocation, getTextContent, hasAttribute, isElement, isTemplate, isTextNode, parseHtml, parseHtmlFragment, walk, } from "./parse.js";
 const VOID_ELEMENTS = new Set([
     "area",
     "base",
@@ -30,11 +30,16 @@ class HtmlCompositionValidator {
     projectRoot;
     entry;
     compositionDir;
-    document;
+    fragment;
+    shellPresent;
+    shellDiagnostics;
     propsOverrides;
     defaultPropsValue = Object.freeze({});
     props;
+    format;
     metadata = null;
+    declaredFormat = null;
+    formatUnresolved = false;
     controller = null;
     documentValid = true;
     fixedFactsValid = false;
@@ -44,26 +49,36 @@ class HtmlCompositionValidator {
     audioClips = [];
     embeddedAudioClips = [];
     transcriptClips = [];
-    constructor(options, document) {
+    constructor(options, fragment, shell) {
         this.projectRoot = path.resolve(options.projectRoot);
         this.entry = options.entry.replaceAll("\\", "/");
         this.compositionDir = path.dirname(path.resolve(this.projectRoot, this.entry));
-        this.document = document;
+        this.fragment = fragment;
+        this.shellPresent = shell.present;
+        this.shellDiagnostics = shell.diagnostics;
         this.propsOverrides = options.props;
         this.props = this.defaultPropsValue;
+        this.format = options.format;
     }
     async run() {
-        this.validateDoctype();
-        const adapter = createParse5Adapter(this.document);
+        if (this.shellDiagnostics.length > 0) {
+            this.documentValid = false;
+            this.diagnostics.push(...this.shellDiagnostics);
+        }
+        const adapter = createParse5Adapter(this.fragment);
         const read = readCompositionDescriptor(adapter, {
             path: this.entry,
             resolvePath: (raw) => this.resolveControllerPath(raw),
+            rootScope: "fragment",
         });
         this.diagnostics.push(...read.diagnostics);
         this.fixedFactsValid = read.valid;
         const readRoot = read.root;
         this.root = readRoot !== null && isElement(readRoot) ? readRoot : null;
-        this.metadata = read.descriptor.metadata;
+        const declared = read.descriptor.metadata;
+        this.declaredFormat = declared?.format ?? null;
+        this.metadata = declared ? resolveCompositionMetadata(declared, this.format) : null;
+        this.formatUnresolved = this.fixedFactsValid && declared !== null && this.metadata === null;
         this.defaultPropsValue = read.descriptor.defaultProps;
         this.controller = read.descriptor.controller;
         this.mergeOverrides();
@@ -81,12 +96,28 @@ class HtmlCompositionValidator {
         });
         this.diagnostics.push(...animation.diagnostics);
         this.validateAnimationTargets(animation.entries);
+        if (this.metadata?.static === true) {
+            for (const entry of animation.entries) {
+                if (!isElement(entry.element)) {
+                    continue;
+                }
+                this.error("STATIC_ANIMATION_UNSUPPORTED", "A static composition cannot use data-fy-anim-* scheduling. Remove the animation or declare duration-in-frames and fps.", this.attributeDetails(entry.element, entry.attributes[0] ?? "data-fy-anim-start"));
+            }
+        }
         const media = readMediaDeclarations(adapter, {
             path: this.entry,
             includeTemplateContent: true,
             props: this.props,
         });
         this.diagnostics.push(...media.diagnostics);
+        if (this.metadata?.static === true) {
+            for (const declaration of [...media.audio, ...media.embedded]) {
+                if (!isElement(declaration.element)) {
+                    continue;
+                }
+                this.error("STATIC_MEDIA_UNSUPPORTED", "A static composition is visual-only and cannot declare audio or video. Put audio on a timeline track instead.", this.elementDetails(declaration.element));
+            }
+        }
         await this.validateMediaFiles(media.audio, media.embedded);
         const transcripts = readTranscriptDeclarations(adapter, {
             path: this.entry,
@@ -94,13 +125,30 @@ class HtmlCompositionValidator {
             props: this.props,
         });
         this.diagnostics.push(...transcripts.diagnostics);
+        if (this.metadata?.static === true) {
+            for (const declaration of transcripts.declarations) {
+                if (!isElement(declaration.element)) {
+                    continue;
+                }
+                this.error("STATIC_MEDIA_UNSUPPORTED", "A static composition is visual-only and cannot declare transcripts. Put captions on a timeline instead.", this.elementDetails(declaration.element));
+            }
+        }
         await this.validateTranscriptFiles(transcripts.declarations);
         await this.validateOrdinaryAssets();
+        await this.validateRemoteFonts();
         const metadata = this.metadata;
+        const declaredFormat = this.declaredFormat;
         const root = this.root;
-        const info = metadata && root && this.fixedFactsValid && this.overridesValid && this.controllerFileValid && this.documentValid
+        const info = metadata &&
+            declaredFormat &&
+            root &&
+            this.fixedFactsValid &&
+            this.overridesValid &&
+            this.controllerFileValid &&
+            this.documentValid
             ? {
                 metadata,
+                declaredFormat,
                 defaultProps: this.defaultPropsValue,
                 controller: this.controller,
                 audioClips: Object.freeze([...this.audioClips]),
@@ -108,7 +156,7 @@ class HtmlCompositionValidator {
                 transcriptClips: Object.freeze([...this.transcriptClips]),
             }
             : null;
-        return { info, diagnostics: this.finishDiagnostics() };
+        return { info, formatUnresolved: this.formatUnresolved, diagnostics: this.finishDiagnostics() };
     }
     report(severity, code, message, details) {
         const diagnostic = {
@@ -187,23 +235,6 @@ class HtmlCompositionValidator {
             return leftColumn - rightColumn;
         });
     }
-    validateDoctype() {
-        const doctype = getDocumentDoctype(this.document);
-        if (!doctype) {
-            this.documentValid = false;
-            this.error("COMPOSITION_INVALID", "Composition documents must start with <!doctype html>.", {
-                line: 1,
-                column: 1,
-            });
-            return;
-        }
-        if (doctype.name.toLowerCase() !== "html") {
-            this.documentValid = false;
-            this.error("COMPOSITION_INVALID", "Composition documents must use the HTML doctype.", {
-                ...this.locationDetails(doctype.sourceCodeLocation ?? undefined),
-            });
-        }
-    }
     mergeOverrides() {
         try {
             this.props = mergeProps(this.defaultPropsValue, this.propsOverrides);
@@ -238,7 +269,7 @@ class HtmlCompositionValidator {
         return path.relative(this.projectRoot, path.resolve(this.compositionDir, raw)).split(path.sep).join("/");
     }
     validateScripts() {
-        for (const element of findElements(this.document, (candidate) => candidate.tagName === "script")) {
+        for (const element of findElements(this.fragment, (candidate) => candidate.tagName === "script")) {
             if (hasAttribute(element, "data-fy-host")) {
                 continue;
             }
@@ -248,9 +279,91 @@ class HtmlCompositionValidator {
             }
             this.error("SCRIPT_NOT_ALLOWED", "Executable <script> elements are not allowed in a composition; move code into the controller.", this.elementDetails(element, { value: getAttribute(element, "src") }));
         }
+        this.validateImportMaps();
+    }
+    validateImportMaps() {
+        const forbiddenAttributes = ["src", "async", "nomodule", "defer", "crossorigin", "integrity", "referrerpolicy"];
+        for (const element of findElements(this.fragment, (candidate) => candidate.tagName === "script" && getAttribute(candidate, "type")?.toLowerCase() === "importmap")) {
+            if (element.parentNode !== this.fragment) {
+                this.error("IMPORT_MAP_INVALID", "Import maps must be top-level elements in the composition fragment.", this.elementDetails(element));
+                continue;
+            }
+            for (const attribute of forbiddenAttributes) {
+                if (hasAttribute(element, attribute)) {
+                    this.error("IMPORT_MAP_INVALID", `Import maps cannot specify the "${attribute}" attribute.`, this.attributeDetails(element, attribute));
+                }
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(getTextContent(element));
+            }
+            catch (error) {
+                this.error("IMPORT_MAP_INVALID", `Invalid import map JSON: ${errorMessage(error)}`, this.elementDetails(element));
+                continue;
+            }
+            if (!isPlainObject(parsed)) {
+                this.error("IMPORT_MAP_INVALID", "An import map must be a JSON object.", this.elementDetails(element));
+                continue;
+            }
+            this.validateImportMapObject(parsed, element);
+        }
+    }
+    validateImportMapObject(value, element) {
+        const checkSpecifierMap = (map, label) => {
+            if (map === undefined) {
+                return;
+            }
+            if (!isPlainObject(map)) {
+                this.error("IMPORT_MAP_INVALID", `Import map "${label}" must be a JSON object.`, this.elementDetails(element));
+                return;
+            }
+            for (const [specifier, target] of Object.entries(map)) {
+                if (specifier.length === 0) {
+                    this.error("IMPORT_MAP_INVALID", `Import map "${label}" contains an empty specifier.`, this.elementDetails(element));
+                    continue;
+                }
+                if (typeof target !== "string") {
+                    this.error("IMPORT_MAP_INVALID", `Import map "${label}" target for "${specifier}" must be a string.`, this.elementDetails(element, { value: specifier }));
+                    continue;
+                }
+                if (specifier.endsWith("/") && !target.endsWith("/")) {
+                    this.error("IMPORT_MAP_INVALID", `Import map prefix "${specifier}" must map to a target ending in "/".`, this.elementDetails(element, { value: specifier }));
+                }
+                if (isReservedImportSpecifier(specifier)) {
+                    this.error("IMPORT_MAP_INVALID", `Import map specifier "${specifier}" is reserved by Frameyard.`, this.elementDetails(element, { value: specifier, suggestion: "Remove the reserved specifier." }));
+                }
+            }
+        };
+        checkSpecifierMap(value.imports, "imports");
+        if (value.scopes !== undefined) {
+            if (!isPlainObject(value.scopes)) {
+                this.error("IMPORT_MAP_INVALID", 'Import map "scopes" must be a JSON object.', this.elementDetails(element));
+            }
+            else {
+                for (const [scope, map] of Object.entries(value.scopes)) {
+                    if (scope.length === 0) {
+                        this.error("IMPORT_MAP_INVALID", "Import map scopes contain an empty path.", this.elementDetails(element));
+                        continue;
+                    }
+                    checkSpecifierMap(map, `scopes["${scope}"]`);
+                }
+            }
+        }
+        if (value.integrity !== undefined) {
+            if (!isPlainObject(value.integrity)) {
+                this.error("IMPORT_MAP_INVALID", 'Import map "integrity" must be a JSON object.', this.elementDetails(element));
+            }
+            else {
+                for (const [target, integrity] of Object.entries(value.integrity)) {
+                    if (typeof integrity !== "string") {
+                        this.error("IMPORT_MAP_INVALID", `Import map integrity for "${target}" must be a string.`, this.elementDetails(element, { value: target }));
+                    }
+                }
+            }
+        }
     }
     validateUnsupportedElements() {
-        walk(this.document, (node) => {
+        walk(this.fragment, (node) => {
             if (!isElement(node)) {
                 return;
             }
@@ -272,6 +385,15 @@ class HtmlCompositionValidator {
                 if (httpEquiv === "refresh" || httpEquiv === "content-security-policy") {
                     this.error("ELEMENT_NOT_SUPPORTED", `<meta http-equiv="${httpEquiv}"> is not supported in a composition.`, this.attributeDetails(node, "http-equiv"));
                 }
+                else if (!this.shellPresent) {
+                    this.error("ELEMENT_NOT_SUPPORTED", "Document-level <meta> is not supported in a composition fragment; the framework owns the document head.", this.elementDetails(node));
+                }
+                return;
+            }
+            if (tag === "title") {
+                if (!this.shellPresent) {
+                    this.error("ELEMENT_NOT_SUPPORTED", "Document-level <title> is not supported in a composition fragment; the framework owns the document head.", this.elementDetails(node));
+                }
                 return;
             }
             if (tag === "template" && hasAttribute(node, "shadowrootmode")) {
@@ -284,7 +406,7 @@ class HtmlCompositionValidator {
         });
     }
     validateDocumentAttributes() {
-        walk(this.document, (node) => {
+        walk(this.fragment, (node) => {
             if (!isElement(node)) {
                 return;
             }
@@ -295,37 +417,45 @@ class HtmlCompositionValidator {
                 if (/^\s*javascript:/i.test(attribute.value)) {
                     this.error("URL_NOT_ALLOWED", `"javascript:" URLs are not allowed in a composition.`, this.attributeDetails(node, attribute.name, { value: attribute.value }));
                 }
+                if (attribute.name === "data-fy-host") {
+                    this.error("COMPOSITION_INVALID", 'The "data-fy-host" attribute is reserved for framework-injected elements.', this.attributeDetails(node, attribute.name));
+                }
+                if (attribute.name === "data-fy") {
+                    if (attribute.value === "format") {
+                        this.error("COMPOSITION_INVALID", 'data-fy="format" is reserved for framework-injected metadata.', this.attributeDetails(node, attribute.name, { value: attribute.value }));
+                    }
+                    else if (attribute.value === "props") {
+                        if (node.tagName !== "script" || getAttribute(node, "type")?.toLowerCase() !== "application/json") {
+                            this.error("PROPS_INVALID", 'data-fy="props" must be on a <script type="application/json"> block.', this.attributeDetails(node, attribute.name, { value: attribute.value }));
+                        }
+                    }
+                    else {
+                        this.error("BINDING_INVALID", "data-fy is only valid on a JSON props block.", this.attributeDetails(node, attribute.name, { value: attribute.value }));
+                    }
+                }
             }
         });
     }
     validateOutsideRoot() {
-        const body = getElementByTagName(this.document, "body");
         const root = this.root;
-        if (!body || !root) {
+        if (!root) {
             return;
         }
-        const inspect = (parent) => {
-            for (const child of parent.childNodes) {
-                if (child === root) {
-                    continue;
-                }
-                if (isElement(child)) {
-                    if (isDescendantOf(root, child)) {
-                        inspect(child);
-                        continue;
-                    }
-                    if (NON_VISUAL_ELEMENTS.has(child.tagName)) {
-                        continue;
-                    }
-                    this.warning("CONTENT_OUTSIDE_ROOT", "Visual content outside <fy-composition> is not captured; move it inside the composition root.", this.elementDetails(child));
+        for (const child of this.fragment.childNodes) {
+            if (child === root) {
+                continue;
+            }
+            if (isElement(child)) {
+                if (NON_VISUAL_ELEMENTS.has(child.tagName)) {
                     continue;
                 }
-                if (isTextNode(child) && child.value.trim().length > 0) {
-                    this.warning("CONTENT_OUTSIDE_ROOT", "Text outside <fy-composition> is not captured; move it inside the composition root.", this.nodeDetails(child));
-                }
+                this.warning("CONTENT_OUTSIDE_ROOT", "Visual content outside <fy-composition> is not captured; move it inside the composition root.", this.elementDetails(child));
+                continue;
             }
-        };
-        inspect(body);
+            if (isTextNode(child) && child.value.trim().length > 0) {
+                this.warning("CONTENT_OUTSIDE_ROOT", "Text outside <fy-composition> is not captured; move it inside the composition root.", this.nodeDetails(child));
+            }
+        }
     }
     validateBindings(element, repeatDepth) {
         const repeat = getAttribute(element, "data-fy-repeat");
@@ -385,12 +515,6 @@ class HtmlCompositionValidator {
             if (name === "data-fy-repeat" || name === "data-fy-if" || name === "data-fy-text") {
                 continue;
             }
-            if (name === "data-fy") {
-                if (element.tagName !== "script" || getAttribute(element, "type")?.toLowerCase() !== "application/json") {
-                    this.error("BINDING_INVALID", "data-fy is only valid on a JSON props block.", this.attributeDetails(element, name));
-                }
-                continue;
-            }
             if (name.startsWith("data-fy-attr-")) {
                 this.validateAttributeBinding(element, name, attribute.value, inRepeat);
                 continue;
@@ -526,15 +650,73 @@ class HtmlCompositionValidator {
             }
         }
     }
+    async validateRemoteFonts() {
+        const seen = new Set();
+        const report = (url, details) => {
+            if (seen.has(url)) {
+                return;
+            }
+            seen.add(url);
+            this.warning("FONT_REMOTE", `Remote font or stylesheet URL "${url}" is not deterministic. Vendor the font into the project with "npx frameyard font add --file".`, { ...details, url });
+        };
+        const scan = (css, details) => {
+            const stripped = css.replace(/\/\*[\s\S]*?\*\//g, "");
+            for (const match of stripped.matchAll(/@import\s+(?:url\(\s*)?["']?((?:https?:)?\/\/[^"')\s]+)/gi)) {
+                const url = match[1];
+                if (url !== undefined) {
+                    report(url, details);
+                }
+            }
+            for (const block of stripped.matchAll(/@font-face\s*\{([^}]*)\}/gi)) {
+                const body = block[1] ?? "";
+                for (const match of body.matchAll(/url\(\s*["']?((?:https?:)?\/\/[^"')\s]+)/gi)) {
+                    const url = match[1];
+                    if (url !== undefined) {
+                        report(url, details);
+                    }
+                }
+            }
+        };
+        for (const style of findElements(this.fragment, (element) => element.tagName === "style")) {
+            scan(getTextContent(style), this.elementDetails(style));
+        }
+        for (const link of findElements(this.fragment, (element) => element.tagName === "link")) {
+            const rel = getAttribute(link, "rel")?.toLowerCase().split(/\s+/) ?? [];
+            if (!rel.includes("stylesheet")) {
+                continue;
+            }
+            const href = getAttribute(link, "href");
+            if (href === undefined) {
+                continue;
+            }
+            if (isRemote(href)) {
+                report(href, this.attributeDetails(link, "href", { value: href }));
+                continue;
+            }
+            if (!isLocalRelative(href)) {
+                continue;
+            }
+            const absolute = path.resolve(this.compositionDir, href);
+            if (absolute !== this.projectRoot && !absolute.startsWith(this.projectRoot + path.sep)) {
+                continue;
+            }
+            try {
+                scan(await readFile(absolute, "utf8"), { path: href, element: "link", attribute: "href" });
+            }
+            catch {
+                // Missing local stylesheets are already reported by ordinary asset validation.
+            }
+        }
+    }
     async validateOrdinaryAssets() {
         const assets = [];
-        for (const image of findElements(this.document, (element) => element.tagName === "img")) {
+        for (const image of findElements(this.fragment, (element) => element.tagName === "img")) {
             const src = getAttribute(image, "src");
             if (src !== undefined) {
                 assets.push({ element: image, attribute: "src", value: src });
             }
         }
-        for (const link of findElements(this.document, (element) => element.tagName === "link")) {
+        for (const link of findElements(this.fragment, (element) => element.tagName === "link")) {
             const rel = getAttribute(link, "rel")?.toLowerCase().split(/\s+/) ?? [];
             if (!rel.includes("stylesheet")) {
                 continue;
@@ -583,6 +765,7 @@ export async function validateHtmlComposition(options) {
     if (entryPath !== projectRoot && !entryPath.startsWith(projectRoot + path.sep)) {
         return {
             info: null,
+            formatUnresolved: false,
             diagnostics: [
                 {
                     severity: "error",
@@ -600,6 +783,7 @@ export async function validateHtmlComposition(options) {
     catch {
         return {
             info: null,
+            formatUnresolved: false,
             diagnostics: [
                 {
                     severity: "error",
@@ -611,12 +795,15 @@ export async function validateHtmlComposition(options) {
         };
     }
     let document;
+    let fragment;
     try {
         document = parseHtml(html);
+        fragment = parseHtmlFragment(html);
     }
     catch (error) {
         return {
             info: null,
+            formatUnresolved: false,
             diagnostics: [
                 {
                     severity: "error",
@@ -627,9 +814,53 @@ export async function validateHtmlComposition(options) {
             ],
         };
     }
-    const validator = new HtmlCompositionValidator({ ...options, projectRoot }, document);
+    const shell = detectDocumentShell(document, options.entry);
+    const validator = new HtmlCompositionValidator({ ...options, projectRoot }, fragment, shell);
     return validator.run();
 }
+function detectDocumentShell(document, entry) {
+    const diagnostics = [];
+    const path = entry.replaceAll("\\", "/");
+    const suggestion = "Keep only the fragment body and top-level metadata. See docs/migration-0.8.md.";
+    const report = (message, element, location) => {
+        diagnostics.push({
+            severity: "error",
+            code: "COMPOSITION_DOCUMENT_SHELL",
+            message,
+            details: {
+                path,
+                element,
+                ...locationDetails(location),
+                suggestion,
+            },
+        });
+    };
+    const doctype = getDocumentDoctype(document);
+    if (doctype) {
+        report("Compositions are HTML fragments in Frameyard 0.8; remove the <!doctype html> declaration.", "!doctype", getNodeLocation(doctype));
+    }
+    for (const tag of ["html", "head", "body"]) {
+        const explicit = findElements(document, (element) => element.tagName === tag && element.sourceCodeLocation?.startTag !== undefined)[0];
+        if (explicit) {
+            report(`Compositions are HTML fragments in Frameyard 0.8; remove the <${tag}> wrapper.`, tag, getElementLocation(explicit));
+        }
+    }
+    return { present: diagnostics.length > 0, diagnostics };
+}
+function locationDetails(location) {
+    if (!location) {
+        return {};
+    }
+    return {
+        line: location.startLine,
+        column: location.startCol,
+        endLine: location.endLine,
+        endColumn: location.endCol,
+    };
+}
+function isReservedImportSpecifier(specifier) {
+    return specifier === "frameyard" || specifier.startsWith("frameyard/");
+}
 function describeValue(value) {
     if (value === null) {
         return "null";