@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

package/vendor/l5x/lib/model/udts.d.ts

@@ -0,0 +1,34 @@
+/**
+ * User-defined-type reader.
+ *
+ * Only types the export keeps in the `NoFamily` family are user-defined; the
+ * remaining entries in `DataTypes` are the built-in types Studio 5000 writes
+ * out alongside them, and reporting those as UDTs would bury the real ones.
+ * Hidden members are omitted because the export marks them as preprocessor
+ * bookkeeping rather than part of the interface.
+ */
+import type { L5xDocument, L5xUdt } from './types.ts';
+import { type XmlElement } from './xml.ts';
+/**
+ * List every user-defined type's name.
+ *
+ * @param document - The parsed project.
+ * @returns Type names, in written order.
+ */
+export declare function listUdtNames(document: L5xDocument): readonly string[];
+/**
+ * Read user-defined types with their visible members.
+ *
+ * @param document - The parsed project.
+ * @param name - Type name to restrict to; empty or omitted returns every type.
+ * @returns Matching types, in written order. An unknown name yields an empty
+ * list rather than an error, matching the reference reader.
+ */
+export declare function getUdt(document: L5xDocument, name?: string): readonly L5xUdt[];
+/**
+ * Read every user-defined type of a controller.
+ *
+ * @param controller - The controller element.
+ * @returns The types, in written order, each with its visible members.
+ */
+export declare function buildUdts(controller: XmlElement): readonly L5xUdt[];

package/vendor/l5x/lib/model/udts.js

@@ -0,0 +1,81 @@
+/**
+ * User-defined-type reader.
+ *
+ * Only types the export keeps in the `NoFamily` family are user-defined; the
+ * remaining entries in `DataTypes` are the built-in types Studio 5000 writes
+ * out alongside them, and reporting those as UDTs would bury the real ones.
+ * Hidden members are omitted because the export marks them as preprocessor
+ * bookkeeping rather than part of the interface.
+ */
+import { descriptionOf } from "./module.js";
+import { elementChildren, firstChild, optionalAttribute, presentAttribute } from "./xml.js";
+/** The family value that marks a data type as user-defined. */
+const NO_FAMILY = 'NoFamily';
+/**
+ * List every user-defined type's name.
+ *
+ * @param document - The parsed project.
+ * @returns Type names, in written order.
+ */
+export function listUdtNames(document) {
+    return document.udts.map(udt => udt.name);
+}
+/**
+ * Read user-defined types with their visible members.
+ *
+ * @param document - The parsed project.
+ * @param name - Type name to restrict to; empty or omitted returns every type.
+ * @returns Matching types, in written order. An unknown name yields an empty
+ * list rather than an error, matching the reference reader.
+ */
+export function getUdt(document, name = '') {
+    if (name === '')
+        return document.udts;
+    return document.udts.filter(udt => udt.name === name);
+}
+/**
+ * Read every user-defined type of a controller.
+ *
+ * @param controller - The controller element.
+ * @returns The types, in written order, each with its visible members.
+ */
+export function buildUdts(controller) {
+    return udtElements(controller).map(udt => ({
+        name: optionalAttribute(udt, 'Name', ''),
+        description: descriptionOf(udt),
+        members: udtMembers(udt),
+    }));
+}
+/** The `<DataType>` elements the export keeps in the user-defined family. */
+function udtElements(controller) {
+    const dataTypes = firstChild(controller, 'DataTypes');
+    if (dataTypes === undefined)
+        return [];
+    return elementChildren(dataTypes, 'DataType').filter(udt => udt.attrs['Family'] === NO_FAMILY);
+}
+/** One type's visible members, in written order. */
+function udtMembers(udt) {
+    const members = firstChild(udt, 'Members');
+    if (members === undefined)
+        return [];
+    const results = [];
+    for (const member of elementChildren(members, 'Member')) {
+        if (member.attrs['Hidden'] === 'true')
+            continue;
+        const entry = {
+            name: optionalAttribute(member, 'Name', ''),
+            dataType: optionalAttribute(member, 'DataType', ''),
+        };
+        const dimension = optionalAttribute(member, 'Dimension', '0');
+        if (dimension !== '0')
+            entry.dimension = Number.parseInt(dimension, 10);
+        const description = descriptionOf(member);
+        if (description !== '')
+            entry.description = description;
+        const radix = presentAttribute(member, 'Radix');
+        if (radix !== undefined)
+            entry.radix = radix;
+        results.push(entry);
+    }
+    return results;
+}

package/vendor/l5x/lib/model/xml.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The XML access layer the L5X readers navigate through.
+ *
+ * `fast-xml-parser` runs in preserved order, so a document is an array of
+ * name-keyed nodes and the export's element order survives parsing. Nothing
+ * outside this module touches that array: readers ask for children, an
+ * attribute, or an element's text and get plain values back.
+ *
+ * Text follows the reference parser's ElementTree semantics, which is the
+ * behavior the readers reproduce. An element's text is the concatenated
+ * character data directly inside it — text nodes and CDATA sections, in order —
+ * and stops at the first child element; a comment contributes nothing. The
+ * readers then decide whether to strip, because the reference strips
+ * descriptions and ladder text but keeps Structured Text lines verbatim.
+ */
+/** An element's attributes, exactly as the export wrote them (always strings). */
+interface XmlAttributes {
+    readonly [name: string]: string;
+}
+/** One parsed element, in whatever position the export wrote it. */
+export interface XmlElement {
+    /** The element's tag name; a non-element node has a reserved name instead. */
+    readonly name: string;
+    /** The element's direct children, in written order; empty for an empty element. */
+    readonly children: readonly XmlNode[];
+    /** The element's attributes; empty for an element with none. */
+    readonly attrs: XmlAttributes;
+}
+/** A node inside an element: a child element, character data, or a comment. */
+export type XmlNode = 
+/** A child element, with its own children and attributes. */
+XmlElement
+/** Character data between elements, or inside an empty element. */
+ | {
+    readonly name: '#text';
+    readonly text: string;
+}
+/** A CDATA section, whose character data is reported as this element's text. */
+ | {
+    readonly name: '#cdata';
+    readonly text: string;
+}
+/** A comment, which contributes no text. */
+ | {
+    readonly name: '#comment';
+    readonly text: string;
+};
+/**
+ * Parse XML text into preserved-order nodes, one per top-level node.
+ *
+ * The document is validated first so a malformed export is refused with the
+ * parser's own description of what is wrong — an unclosed tag, a stray
+ * character — rather than with the partial tree a permissive parse would leave
+ * behind. This is a parse failure, not a recoverable one: a reader that went on
+ * would report an export that is not there.
+ *
+ * @param xml - The document text.
+ * @returns Every top-level node, in written order.
+ * @throws L5xParseError When the text is not well-formed XML.
+ */
+export declare function parseXml(xml: string): readonly XmlNode[];
+/**
+ * The document element.
+ *
+ * An export begins with an XML declaration, which parses as a top-level node
+ * named `?xml`, and may carry processing instructions or a DOCTYPE before the
+ * root; the first node that is neither is the document element.
+ *
+ * @param nodes - Top-level nodes from {@link parseXml}.
+ * @returns The root element.
+ * @throws L5xParseError When the document has no root element.
+ */
+export declare function documentRoot(nodes: readonly XmlNode[]): XmlElement;
+/**
+ * Direct children of an element that carry a tag name.
+ *
+ * @param element - Element to read.
+ * @param name - Tag name to match, case-sensitively.
+ * @returns Matching children, in written order.
+ */
+export declare function elementChildren(element: XmlElement, name: string): readonly XmlElement[];
+/**
+ * The first direct child with a tag name.
+ *
+ * @param element - Element to read.
+ * @param name - Tag name to match, case-sensitively.
+ * @returns The first matching child, or undefined when there is none.
+ */
+export declare function firstChild(element: XmlElement, name: string): XmlElement | undefined;
+/**
+ * An attribute value.
+ *
+ * @param element - Element to read.
+ * @param name - Attribute name.
+ * @returns The value, exactly as written.
+ * @throws L5xParseError When the element does not carry the attribute.
+ */
+export declare function attribute(element: XmlElement, name: string): string;
+/**
+ * An attribute value, or a caller-chosen substitute when it is absent.
+ *
+ * @param element - Element to read.
+ * @param name - Attribute name.
+ * @param fallback - Value returned when the attribute is absent.
+ * @returns The value, exactly as written, or the fallback.
+ */
+export declare function optionalAttribute(element: XmlElement, name: string, fallback: string): string;
+/**
+ * An attribute value, or undefined when it is absent or empty.
+ *
+ * The reference readers emit a field only when the export declares something to
+ * put in it, so an attribute written as `Radix=""` is reported as undeclared.
+ *
+ * @param element - Element to read.
+ * @param name - Attribute name.
+ * @returns The value, or undefined when it is absent or empty.
+ */
+export declare function presentAttribute(element: XmlElement, name: string): string | undefined;
+/**
+ * An element's text: its character data, stopping at the first child element.
+ *
+ * A comment contributes nothing, which is what the reference parser reports.
+ * The loop keeps its element arm as the break condition even though `isElement`
+ * already answered it, because that answer is what narrows `child` to a node
+ * that carries text.
+ *
+ * @param element - Element to read.
+ * @returns The text, or undefined when the element holds none. The caller
+ * decides whether to strip it.
+ */
+export declare function nodeText(element: XmlElement): string | undefined;
+/**
+ * Whether a node is an element rather than character data or a comment.
+ *
+ * @param node - Node to classify.
+ * @returns True when the node carries children rather than character data.
+ */
+export declare function isElement(node: XmlNode): node is XmlElement;
+export {};

package/vendor/l5x/lib/model/xml.js

@@ -0,0 +1,291 @@
+/**
+ * The XML access layer the L5X readers navigate through.
+ *
+ * `fast-xml-parser` runs in preserved order, so a document is an array of
+ * name-keyed nodes and the export's element order survives parsing. Nothing
+ * outside this module touches that array: readers ask for children, an
+ * attribute, or an element's text and get plain values back.
+ *
+ * Text follows the reference parser's ElementTree semantics, which is the
+ * behavior the readers reproduce. An element's text is the concatenated
+ * character data directly inside it — text nodes and CDATA sections, in order —
+ * and stops at the first child element; a comment contributes nothing. The
+ * readers then decide whether to strip, because the reference strips
+ * descriptions and ladder text but keeps Structured Text lines verbatim.
+ */
+import { XMLParser } from 'fast-xml-parser';
+import { SyntaxValidator } from 'fast-xml-validator';
+import { L5xParseError } from "./errors.js";
+const TEXT_NODE = '#text';
+const COMMENT_NODE = '#comment';
+const parser = new XMLParser({
+    preserveOrder: true,
+    ignoreAttributes: false,
+    attributeNamePrefix: '',
+    attributesGroupName: ':@',
+    // The reference parser yields attribute values as text and never coerces
+    // them, so `Number="0"` stays `"0"` and `parseInt` decides what it means.
+    parseAttributeValue: false,
+    parseTagValue: false,
+    trimValues: false,
+    processEntities: true,
+    // CDATA is written in real exports. Naming the key keeps CDATA structurally
+    // distinct from text at THIS boundary; `nodeText` merges the two, which is
+    // what ElementTree reports, while comment nodes stay distinguishable.
+    cdataPropName: '#cdata',
+    // The reference parser reports a comment as its own node, so the readers can
+    // tell one from character data. Left unnamed, the parser drops comments
+    // entirely.
+    commentPropName: '#comment',
+});
+const CDATA_NODE = '#cdata';
+/**
+ * Parse XML text into preserved-order nodes, one per top-level node.
+ *
+ * The document is validated first so a malformed export is refused with the
+ * parser's own description of what is wrong — an unclosed tag, a stray
+ * character — rather than with the partial tree a permissive parse would leave
+ * behind. This is a parse failure, not a recoverable one: a reader that went on
+ * would report an export that is not there.
+ *
+ * @param xml - The document text.
+ * @returns Every top-level node, in written order.
+ * @throws L5xParseError When the text is not well-formed XML.
+ */
+export function parseXml(xml) {
+    assertWellFormed(xml);
+    try {
+        const parsed = parser.parse(xml);
+        return normalise(asSequence(parsed));
+    }
+    catch (error) {
+        /* v8 ignore next -- nesting past the parser's limit is a bare Error; the fallback keeps the message readable. */
+        throw new L5xParseError(`Malformed XML: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** The parser's top-level value, which preservation makes a sequence of nodes. */
+function asSequence(parsed) {
+    /* v8 ignore next -- preservation always returns an array; this narrows the parser's any-typed result for the adapter below. */
+    return Array.isArray(parsed) ? parsed : [];
+}
+/**
+ * Refuse text that is not well-formed XML.
+ *
+ * The validator reports what is wrong — an unclosed tag, a repeated attribute,
+ * a stray character — where a permissive parse would return a partial tree that
+ * a reader would then report as a project. This is a parse failure, not a
+ * recoverable one.
+ *
+ * @param xml - The document text.
+ * @throws L5xParseError When the text is not well-formed XML.
+ */
+function assertWellFormed(xml) {
+    try {
+        SyntaxValidator.validate(xml);
+    }
+    catch (error) {
+        /* v8 ignore next -- the validator reports refusal as a ValidationError; the literal fallback only covers a non-Error throw. */
+        throw new L5xParseError(`Malformed XML: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * The document element.
+ *
+ * An export begins with an XML declaration, which parses as a top-level node
+ * named `?xml`, and may carry processing instructions or a DOCTYPE before the
+ * root; the first node that is neither is the document element.
+ *
+ * @param nodes - Top-level nodes from {@link parseXml}.
+ * @returns The root element.
+ * @throws L5xParseError When the document has no root element.
+ */
+export function documentRoot(nodes) {
+    for (const node of nodes) {
+        if (isElement(node) && !node.name.startsWith('?'))
+            return node;
+    }
+    throw new L5xParseError('Malformed XML: no root element');
+}
+/**
+ * Direct children of an element that carry a tag name.
+ *
+ * @param element - Element to read.
+ * @param name - Tag name to match, case-sensitively.
+ * @returns Matching children, in written order.
+ */
+export function elementChildren(element, name) {
+    const matches = [];
+    for (const child of element.children) {
+        if (isElement(child) && child.name === name)
+            matches.push(child);
+    }
+    return matches;
+}
+/**
+ * The first direct child with a tag name.
+ *
+ * @param element - Element to read.
+ * @param name - Tag name to match, case-sensitively.
+ * @returns The first matching child, or undefined when there is none.
+ */
+export function firstChild(element, name) {
+    for (const child of element.children) {
+        if (isElement(child) && child.name === name)
+            return child;
+    }
+    return undefined;
+}
+/**
+ * An attribute value.
+ *
+ * @param element - Element to read.
+ * @param name - Attribute name.
+ * @returns The value, exactly as written.
+ * @throws L5xParseError When the element does not carry the attribute.
+ */
+export function attribute(element, name) {
+    const value = element.attrs[name];
+    if (value === undefined) {
+        throw new L5xParseError(`Malformed XML: <${element.name}> has no ${name} attribute`);
+    }
+    return value;
+}
+/**
+ * An attribute value, or a caller-chosen substitute when it is absent.
+ *
+ * @param element - Element to read.
+ * @param name - Attribute name.
+ * @param fallback - Value returned when the attribute is absent.
+ * @returns The value, exactly as written, or the fallback.
+ */
+export function optionalAttribute(element, name, fallback) {
+    return element.attrs[name] ?? fallback;
+}
+/**
+ * An attribute value, or undefined when it is absent or empty.
+ *
+ * The reference readers emit a field only when the export declares something to
+ * put in it, so an attribute written as `Radix=""` is reported as undeclared.
+ *
+ * @param element - Element to read.
+ * @param name - Attribute name.
+ * @returns The value, or undefined when it is absent or empty.
+ */
+export function presentAttribute(element, name) {
+    return element.attrs[name] || undefined;
+}
+/**
+ * An element's text: its character data, stopping at the first child element.
+ *
+ * A comment contributes nothing, which is what the reference parser reports.
+ * The loop keeps its element arm as the break condition even though `isElement`
+ * already answered it, because that answer is what narrows `child` to a node
+ * that carries text.
+ *
+ * @param element - Element to read.
+ * @returns The text, or undefined when the element holds none. The caller
+ * decides whether to strip it.
+ */
+export function nodeText(element) {
+    let text = '';
+    for (const child of element.children) {
+        if (isElement(child))
+            break;
+        /* v8 ignore next -- a node named as an element is already excluded above, so the comment test is the only remaining arm. */
+        if (child.name !== COMMENT_NODE)
+            text += child.text;
+    }
+    return text === '' ? undefined : text;
+}
+/**
+ * Whether a node is an element rather than character data or a comment.
+ *
+ * @param node - Node to classify.
+ * @returns True when the node carries children rather than character data.
+ */
+export function isElement(node) {
+    return node.name !== TEXT_NODE && node.name !== COMMENT_NODE && node.name !== CDATA_NODE;
+}
+/**
+ * Convert the parser's own object layout into {@link XmlNode} values.
+ *
+ * `fast-xml-parser` keys a preserved-order node by its tag name and carries
+ * children and attributes under reserved keys. The reserved text and comment
+ * names carry their character data directly, an element name carries the array
+ * of its children, and an attribute group appears only on an element that has
+ * attributes.
+ *
+ * @param value - The children at one position of a parsed document.
+ * @returns The equivalent nodes, in written order.
+ */
+/* v8 ignore start -- adapter for fast-xml-parser's preserved-order output; every arm in
+   this region is one that layout does not produce, and the suite holds every arm a real
+   export does reach. */
+function normalise(value) {
+    const nodes = [];
+    for (const entry of value) {
+        if (isRecord(entry))
+            nodes.push(...nodesOf(entry));
+    }
+    return nodes;
+}
+/** Every node of one parsed entry, in written order. */
+function nodesOf(entry) {
+    const nodes = [];
+    for (const name of Object.keys(entry)) {
+        if (name === ':@')
+            continue;
+        const children = entry[name];
+        if (name === TEXT_NODE)
+            nodes.push(characterData(entry));
+        else if (name === COMMENT_NODE)
+            nodes.push({ name: COMMENT_NODE, text: '' });
+        else if (name === CDATA_NODE)
+            nodes.push(cdataNode(children));
+        else if (Array.isArray(children))
+            nodes.push(elementNode(name, children, entry));
+    }
+    return nodes;
+}
+/** Character data carried by an entry that declares the text node name. */
+function characterData(entry) {
+    const text = entry[TEXT_NODE];
+    return { name: TEXT_NODE, text: typeof text === 'string' ? text : '' };
+}
+/** A CDATA section, which nests the character data it carries. */
+function cdataNode(children) {
+    let text = '';
+    if (Array.isArray(children)) {
+        for (const child of children) {
+            if (isRecord(child))
+                text += cdataTextOf(child);
+        }
+    }
+    return { name: CDATA_NODE, text };
+}
+/** The character data inside one entry of a CDATA section. */
+function cdataTextOf(child) {
+    const text = child[TEXT_NODE];
+    return typeof text === 'string' ? text : '';
+}
+/** One element entry, with its children and attributes. */
+function elementNode(name, children, entry) {
+    return { name, children: normalise(children), attrs: attributesOf(entry) };
+}
+/** The attribute group of an element entry, or an empty group when it has none. */
+function attributesOf(entry) {
+    const raw = entry[':@'];
+    const attrs = {};
+    if (isRecord(raw)) {
+        for (const key of Object.keys(raw)) {
+            const value = raw[key];
+            if (typeof value === 'string')
+                attrs[key] = value;
+        }
+    }
+    return attrs;
+}
+/** Whether a parsed value is a keyed record rather than a primitive. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/vendor/l5x/lib/model/xref.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Cross-reference search — which symbols a project's logic references, and where.
+ *
+ * The index is built from decoded ladder NeutralText and Structured Text lines,
+ * not from the raw XML, so a symbol is reported the way a reader of the logic
+ * would write it: `Motor_1.Running` is one symbol and `Motor_1` is also its own
+ * entry, because a caller asking "where is Motor_1 used" expects the dotted
+ * references too.
+ *
+ * Instruction mnemonics and language keywords are excluded — `XIC`, `OTE`, `IF`,
+ * and `AND` are not tags, and reporting them would bury every real answer. The
+ * index is cached per parsed document, so asking one project several questions
+ * scans its logic once.
+ */
+import type { L5xDocument, L5xSymbolUsage } from './types.ts';
+/**
+ * Search the project's logic for symbols matching a pattern.
+ *
+ * The pattern is a regular expression, evaluated case-insensitively. A pattern
+ * that is not a valid expression is searched for literally instead, so a tag
+ * whose name contains regex punctuation still finds its uses.
+ *
+ * @param document - The parsed project to search.
+ * @param pattern - Regular expression, or literal text when it does not compile.
+ * @returns One entry per matching symbol, in the order the symbols were first
+ * seen, each with every reference to it and an empty result when nothing matched.
+ */
+export declare function searchLogic(document: L5xDocument, pattern: string): readonly L5xSymbolUsage[];