@aryacode/dsh-engineering 0.6.0 → 0.8.0

package/vendor/ftview/lib/edit/operations.d.ts

@@ -29,7 +29,52 @@ export interface TagUpsertOperation {
     readonly type?: string;
 }
 /** One staged edit. */
-export type EditOperation = DisplaySetOperation | DisplayAddOperation | TagUpsertOperation;
+export type EditOperation = DisplaySetOperation | DisplayAddOperation | TagUpsertOperation | DisplayCreateOperation | ObjectAddOperation | ObjectSetOperation | ObjectDeleteOperation | ObjectOrderOperation;
+/** Create a new display file from a schema-valid skeleton. */
+export interface DisplayCreateOperation {
+    readonly kind: 'display_create';
+    readonly file: string;
+    readonly name: string;
+    readonly width: number;
+    readonly height: number;
+    readonly displayType?: string;
+    readonly backColor?: string;
+    readonly displayNumber?: number;
+}
+/** Add one object to a display, optionally inside a named group. */
+export interface ObjectAddOperation {
+    readonly kind: 'object_add';
+    readonly file: string;
+    readonly type: string;
+    readonly name: string;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly parent?: string;
+    readonly index?: number;
+    readonly connections?: Readonly<Record<string, string>>;
+    readonly caption?: string;
+}
+/** Change attributes, caption or connections on an existing object. */
+export interface ObjectSetOperation {
+    readonly kind: 'object_set';
+    readonly file: string;
+    readonly object: string;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly caption?: string;
+    readonly connections?: Readonly<Record<string, string>>;
+}
+/** Remove one object from a display. */
+export interface ObjectDeleteOperation {
+    readonly kind: 'object_delete';
+    readonly file: string;
+    readonly object: string;
+}
+/** Move one object within its siblings, changing z-order. */
+export interface ObjectOrderOperation {
+    readonly kind: 'object_order';
+    readonly file: string;
+    readonly object: string;
+    readonly index: number;
+}
 /** Escape one XML attribute value. */
 export declare function escapeAttribute(value: string): string;
 /** Escape one CSV cell when it needs quoting. */
@@ -60,3 +105,42 @@ export declare function renameDisplay(xml: string, name: string): string;
  * @returns The modified CSV.
  */
 export declare function upsertTag(csv: string, tag: TagUpsertOperation): string;
+/**
+ * Build a new display document from a schema-valid skeleton.
+ *
+ * @param op - Display identity and size.
+ * @returns Whole XML text.
+ */
+export declare function createDisplay(op: DisplayCreateOperation): string;
+/**
+ * Add one object to a display.
+ *
+ * @param xml - Display XML.
+ * @param op - Object type, name, geometry and connections.
+ * @returns The modified XML.
+ */
+export declare function addObject(xml: string, op: ObjectAddOperation): string;
+/**
+ * Change attributes and connections on an existing object.
+ *
+ * @param xml - Display XML.
+ * @param op - Target object and the changes.
+ * @returns The modified XML.
+ */
+export declare function setObject(xml: string, op: ObjectSetOperation): string;
+/**
+ * Remove one object.
+ *
+ * @param xml - Display XML.
+ * @param op - Target object.
+ * @returns The modified XML.
+ */
+export declare function deleteObject(xml: string, op: ObjectDeleteOperation): string;
+/**
+ * Move one object within its siblings.
+ *
+ * @param xml - Display XML.
+ * @param op - Target object and the new index.
+ * @returns The modified XML.
+ */
+export declare function orderObject(xml: string, op: ObjectOrderOperation): string;

package/vendor/ftview/lib/edit/operations.js

@@ -9,6 +9,7 @@
  */
 import { EngineeringError } from "../core.js";
 import { splitCsv } from "../model.js";
+import { decodeEntities, findNamed, firstChildOfType, insertChild, parseDisplayTree, removeNode, renderElement, setAttribute as setNodeAttribute } from "../display-tree.js";
 /** Escape one XML attribute value. */
 export function escapeAttribute(value) {
     return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
@@ -124,3 +125,203 @@ export function upsertTag(csv, tag) {
         lines.push(cells.map(encodeCell).join(';'));
     return lines.join(eol);
 }
+/** Elements that are parts of an object, never objects themselves. */
+const RESERVED = new Set(['gfx', 'display', 'displaySettings', 'connections', 'connection', 'states', 'state', 'caption', 'imageSettings', 'animations', 'parameters', 'parameter', 'font', 'color']);
+/** Depth of one node below the root. */
+function depthOf(root, target) {
+    let found = -1;
+    const walkNode = (node, depth) => {
+        if (found >= 0)
+            return;
+        if (node === target) {
+            found = depth;
+            return;
+        }
+        for (const child of node.children)
+            walkNode(child, depth + 1);
+    };
+    walkNode(root, 0);
+    return found;
+}
+/** Parent of one node, or undefined for the root. */
+function parentOf(root, target) {
+    let found;
+    const walkNode = (node) => {
+        if (found !== undefined)
+            return;
+        for (const child of node.children) {
+            if (child === target) {
+                found = node;
+                return;
+            }
+            walkNode(child);
+        }
+    };
+    walkNode(root);
+    return found;
+}
+/** Validate an object name and element type before writing anything. */
+function assertObjectStyle(type, name) {
+    if (!/^[A-Za-z_][\w.:-]*$/u.test(type))
+        throw new EngineeringError('INVALID_OBJECT_TYPE', `${JSON.stringify(type)} is not an XML element name.`, 'Pass the object element name as the export writes it, for example "momentaryButton".');
+    if (RESERVED.has(type))
+        throw new EngineeringError('INVALID_OBJECT_TYPE', `${type} is part of a display, not an object type.`, 'Pass an object element such as "text", "panel", "momentaryButton" or "numericDisplay".');
+    if (!/^[A-Za-z_][\w .-]{0,79}$/u.test(name))
+        throw new EngineeringError('INVALID_OBJECT_NAME', `${JSON.stringify(name)} is not an object name.`, 'Use letters, digits, spaces, dots, underscores or dashes, at most 80 characters.');
+}
+/** A `<connections>` block at one depth. */
+function connectionsXml(connections, depth) {
+    const lines = Object.entries(connections).map(([name, expression]) => {
+        if (!/^[A-Za-z_][\w.:-]*$/u.test(name))
+            throw new EngineeringError('INVALID_CONNECTION', `${JSON.stringify(name)} is not a connection name.`, 'Pass the connection as the export writes it, for example "Value" or "Visibility".');
+        return `${'    '.repeat(depth + 1)}<connection name="${escapeAttribute(name)}" expression="${escapeAttribute(expression)}"/>\n`;
+    });
+    return `${'    '.repeat(depth)}<connections>\n${lines.join('')}${'    '.repeat(depth)}</connections>\n`;
+}
+/**
+ * Build a new display document from a schema-valid skeleton.
+ *
+ * @param op - Display identity and size.
+ * @returns Whole XML text.
+ */
+export function createDisplay(op) {
+    const settings = {};
+    if (op.displayType !== undefined)
+        settings.displayType = op.displayType;
+    settings.width = String(op.width);
+    settings.height = String(op.height);
+    if (op.backColor !== undefined)
+        settings.backColor = op.backColor;
+    if (op.displayNumber !== undefined)
+        settings.displayNumber = String(op.displayNumber);
+    const attributes = Object.entries(settings).map(([name, value]) => ` ${name}="${escapeAttribute(value)}"`).join('');
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<gfx xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Gfx-ME17.xsd">\n    <displaySettings${attributes}/>\n</gfx>\n`;
+}
+/**
+ * Add one object to a display.
+ *
+ * @param xml - Display XML.
+ * @param op - Object type, name, geometry and connections.
+ * @returns The modified XML.
+ */
+export function addObject(xml, op) {
+    assertObjectStyle(op.type, op.name);
+    const tree = parseDisplayTree(xml);
+    if (op.parent !== undefined) {
+        const parent = findNamed(tree.root, op.parent);
+        if (parent === undefined)
+            throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.parent)} in this display.`, 'Call ftview_get to see the object names, then add inside an existing group.');
+        const depth = depthOf(tree.root, parent);
+        const attributes = { name: escapeAttribute(op.name), ...op.attributes };
+        const innerConnections = op.connections === undefined ? '' : connectionsXml(op.connections, depth + 1);
+        const element = renderElement(op.type, attributes, innerConnections === '' ? undefined : innerConnections, depth + 1);
+        return insertChild(tree, parent, element, op.index);
+    }
+    const attributes = { name: escapeAttribute(op.name), ...op.attributes };
+    if (op.caption !== undefined && attributes.caption === undefined)
+        attributes.caption = escapeAttribute(op.caption);
+    const innerConnections = op.connections === undefined ? '' : connectionsXml(op.connections, 1);
+    const element = renderElement(op.type, attributes, innerConnections === '' ? undefined : innerConnections, 1);
+    return insertChild(tree, tree.root, element, op.index);
+}
+/**
+ * Change attributes and connections on an existing object.
+ *
+ * @param xml - Display XML.
+ * @param op - Target object and the changes.
+ * @returns The modified XML.
+ */
+export function setObject(xml, op) {
+    let current = xml;
+    for (const [name, value] of Object.entries(op.attributes)) {
+        if (!/^[A-Za-z_][\w.:-]*$/u.test(name))
+            throw new EngineeringError('INVALID_ATTRIBUTE', `${JSON.stringify(name)} is not an XML attribute name.`, 'Pass a plain attribute name such as "visible" or "left".');
+        const tree = parseDisplayTree(current);
+        const node = findNamed(tree.root, op.object);
+        if (node === undefined)
+            throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+        current = setNodeAttribute(tree, node, name, value);
+    }
+    if (op.caption !== undefined) {
+        if (op.caption.length > 2000)
+            throw new EngineeringError('INVALID_CAPTION', 'A caption is limited to 2000 characters.', 'Shorten the caption.');
+        const tree = parseDisplayTree(current);
+        const node = findNamed(tree.root, op.object);
+        if (node === undefined)
+            throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+        current = setNodeAttribute(tree, node, 'caption', op.caption);
+    }
+    if (op.connections !== undefined) {
+        for (const name of Object.keys(op.connections)) {
+            if (!/^[A-Za-z_][\w.:-]*$/u.test(name))
+                throw new EngineeringError('INVALID_CONNECTION', `${JSON.stringify(name)} is not a connection name.`, 'Pass the connection name as the export writes it.');
+            const tree = parseDisplayTree(current);
+            const node = findNamed(tree.root, op.object);
+            if (node === undefined)
+                throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+            const expression = op.connections[name];
+            let block = firstChildOfType(node, 'connections');
+            if (block === undefined) {
+                const depth = depthOf(tree.root, node);
+                const inserted = insertChild(tree, node, connectionsXml({ [name]: expression }, depth + 1));
+                current = inserted;
+                continue;
+            }
+            const existing = block.children.find(child => child.type === 'connection' && decodeEntities(child.attributes.name ?? '') === name);
+            if (existing !== undefined) {
+                const existingTree = parseDisplayTree(current);
+                const existingBlock = findNamed(existingTree.root, op.object);
+                if (existingBlock === undefined)
+                    throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+                const connection = existingBlock.children.find(child => child.type === 'connections')?.children.find(child => child.type === 'connection' && decodeEntities(child.attributes.name ?? '') === name);
+                if (connection === undefined)
+                    throw new EngineeringError('COMPONENT_NOT_FOUND', `Connection ${JSON.stringify(name)} disappeared while editing.`, 'Reopen the display and retry.');
+                current = setNodeAttribute(existingTree, connection, 'expression', expression);
+            }
+            else {
+                const depth = depthOf(tree.root, block);
+                current = insertChild(tree, block, `${'    '.repeat(depth + 1)}<connection name="${escapeAttribute(name)}" expression="${escapeAttribute(expression)}"/>\n`);
+            }
+        }
+    }
+    return current;
+}
+/**
+ * Remove one object.
+ *
+ * @param xml - Display XML.
+ * @param op - Target object.
+ * @returns The modified XML.
+ */
+export function deleteObject(xml, op) {
+    const tree = parseDisplayTree(xml);
+    const node = findNamed(tree.root, op.object);
+    if (node === undefined)
+        throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+    return removeNode(tree, node);
+}
+/**
+ * Move one object within its siblings.
+ *
+ * @param xml - Display XML.
+ * @param op - Target object and the new index.
+ * @returns The modified XML.
+ */
+export function orderObject(xml, op) {
+    const tree = parseDisplayTree(xml);
+    const node = findNamed(tree.root, op.object);
+    if (node === undefined)
+        throw new EngineeringError('COMPONENT_NOT_FOUND', `No object is named ${JSON.stringify(op.object)} in this display.`, 'Call ftview_get to see the object names.');
+    const parent = parentOf(tree.root, node);
+    if (parent === undefined)
+        throw new EngineeringError('UNSUPPORTED_TARGET', 'The display root cannot be reordered.', 'Target an object inside the display.');
+    const element = xml.slice(node.start, node.end);
+    const without = removeNode(tree, node);
+    const next = parseDisplayTree(without);
+    const target = op.object;
+    const parentName = parent.type === tree.root.type ? undefined : decodeEntities(parent.attributes.name ?? '');
+    const container = parentName === undefined ? next.root : findNamed(next.root, parentName);
+    if (container === undefined)
+        throw new EngineeringError('COMPONENT_NOT_FOUND', `The parent of ${JSON.stringify(target)} disappeared while reordering.`, 'Reopen the display and retry.');
+    return insertChild(next, container, element, op.index);
+}

package/vendor/ftview/lib/edit/prepare.d.ts

@@ -11,6 +11,7 @@ import { type Coverage, type FsService } from '../core.ts';
 import { type Finding } from '../checks.ts';
 import { type Application } from '../model.ts';
 import { type EditOperation } from './operations.ts';
+import { type SchemaValidation } from '../schema.ts';
 /** One prepared edit set. */
 export interface PreparedEdit {
     /** Files whose text changed, keyed by export-relative path. */
@@ -23,6 +24,8 @@ export interface PreparedEdit {
     readonly findings: readonly Finding[];
     /** Stable hash over the source hashes and the operations. */
     readonly hash: string;
+    /** Vendor-schema validation of the changed and added displays. */
+    readonly schema: SchemaValidation;
 }
 /** Coverage for anything derived from an export. */
 export declare const EDIT_COVERAGE: Coverage;

package/vendor/ftview/lib/edit/prepare.js

@@ -11,7 +11,8 @@ import { createHash } from 'node:crypto';
 import { EngineeringError } from "../core.js";
 import { findingsOf } from "../checks.js";
 import { parseDisplay, parseTagCsv } from "../model.js";
-import { renameDisplay, setAttribute, upsertTag } from "./operations.js";
+import { addObject, createDisplay, deleteObject, orderObject, renameDisplay, setAttribute, setObject, upsertTag } from "./operations.js";
+import { validateSchema } from "../schema.js";
 /** Coverage for anything derived from an export. */
 export const EDIT_COVERAGE = {
     complete: false,
@@ -63,6 +64,31 @@ export async function prepareEdit(fs, app, operations, signal) {
             texts.set(operation.file, setAttribute(current, operation.object, operation.attribute, operation.value));
             continue;
         }
+        if (operation.kind === 'display_create') {
+            if (displayNames.has(operation.name) || added.includes(operation.file)) {
+                throw new EngineeringError('COMPONENT_EXISTS', `A display named ${JSON.stringify(operation.name)} already exists in this export or draft.`, 'Pass a new display name.');
+            }
+            if (app.files.some(file => file.file.toLowerCase() === operation.file.toLowerCase())) {
+                throw new EngineeringError('COMPONENT_EXISTS', `The export already has a file ${operation.file}.`, 'Pass a different file path.');
+            }
+            texts.set(operation.file, createDisplay(operation));
+            added.push(operation.file);
+            displayNames.add(operation.name);
+            continue;
+        }
+        if (operation.kind === 'object_add' || operation.kind === 'object_set' || operation.kind === 'object_delete' || operation.kind === 'object_order') {
+            const known = displayByFile.has(operation.file) || added.includes(operation.file);
+            if (!known) {
+                throw new EngineeringError('COMPONENT_NOT_FOUND', `The draft targets ${operation.file}, which this export no longer contains.`, 'Reopen the export and stage the edit again.');
+            }
+            const current = texts.get(operation.file) ?? await readText(fs, app.root, operation.file, signal);
+            const next = operation.kind === 'object_add' ? addObject(current, operation)
+                : operation.kind === 'object_set' ? setObject(current, operation)
+                    : operation.kind === 'object_delete' ? deleteObject(current, operation)
+                        : orderObject(current, operation);
+            texts.set(operation.file, next);
+            continue;
+        }
         if (operation.kind === 'display_add') {
             const source = app.displays.find(display => display.name === operation.copyFrom);
             if (source === undefined) {
@@ -122,12 +148,20 @@ export async function prepareEdit(fs, app, operations, signal) {
         return !changedFiles.has(file);
     });
     const findings = findingsOf({ displays, tags, tagErrors, diagnostics });
+    // Validate only the documents this draft writes: the unchanged ones were
+    // already read by the session, and re-validating 18 displays per call would
+    // make every edit pay for the whole export.
+    const changedDisplays = [...texts]
+        .filter(([file]) => /\.xml$/iu.test(file) && !/batchimport/iu.test(file))
+        .map(([file, text]) => ({ file, xml: text }));
+    const schema = await validateSchema(changedDisplays);
     const hashInput = app.files.map(file => `${file.file}:${file.sha256}`).join('\n') + '\n' + JSON.stringify(operations);
     return {
         texts,
         added,
         changed: [...app.files.map(file => file.file), ...added],
         findings,
+        schema,
         hash: createHash('sha256').update(hashInput).digest('hex'),
     };
 }