@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,112 @@
+/**
+ * Add-on-instruction reader.
+ *
+ * An AOI carries both its interface — parameters and local tags — and its
+ * internal logic, and both are reported together because an instruction is only
+ * usable when its pins and its behavior are known.
+ */
+import { descriptionOf } from "./module.js";
+import { elementChildren, firstChild, optionalAttribute } from "./xml.js";
+import { routineBody } from "./routines.js";
+/**
+ * List the add-on instructions the controller defines.
+ *
+ * @param document - The parsed project.
+ * @returns One entry per instruction, in written order.
+ */
+export function listAois(document) {
+    return document.aois.map(aoi => ({ name: aoi.name, description: aoi.description, revision: aoi.revision }));
+}
+/**
+ * Read every add-on instruction, with its interface and internal logic.
+ *
+ * @param document - The parsed project.
+ * @returns One definition per instruction, in written order.
+ */
+export function getAois(document) {
+    return document.aois;
+}
+/**
+ * Read one add-on instruction, with its interface and internal logic.
+ *
+ * @param document - The parsed project.
+ * @param name - Instruction name.
+ * @returns The definition, or undefined when the controller does not define
+ * that instruction.
+ */
+export function getAoi(document, name) {
+    return document.aois.find(aoi => aoi.name === name);
+}
+/**
+ * Read every add-on instruction definition of a controller.
+ *
+ * @param controller - The controller element.
+ * @returns The definitions, in written order.
+ */
+export function buildAois(controller) {
+    return aoiElements(controller).map(aoi => ({
+        name: optionalAttribute(aoi, 'Name', ''),
+        description: descriptionOf(aoi),
+        revision: optionalAttribute(aoi, 'Revision', ''),
+        vendor: optionalAttribute(aoi, 'Vendor', ''),
+        parameters: aoiParameters(aoi),
+        localTags: aoiLocalTags(aoi),
+        routines: aoiRoutines(aoi),
+    }));
+}
+/** The `<AddOnInstructionDefinition>` elements, in written order. */
+function aoiElements(controller) {
+    const definitions = firstChild(controller, 'AddOnInstructionDefinitions');
+    return definitions === undefined ? [] : elementChildren(definitions, 'AddOnInstructionDefinition');
+}
+/** One instruction's parameters, in written order. */
+function aoiParameters(aoi) {
+    const parameters = firstChild(aoi, 'Parameters');
+    if (parameters === undefined)
+        return [];
+    const results = [];
+    for (const parameter of elementChildren(parameters, 'Parameter')) {
+        const entry = {
+            name: optionalAttribute(parameter, 'Name', ''),
+            dataType: optionalAttribute(parameter, 'DataType', ''),
+            usage: optionalAttribute(parameter, 'Usage', ''),
+        };
+        const description = descriptionOf(parameter);
+        if (description !== '')
+            entry.description = description;
+        if (parameter.attrs['Required'] === 'true')
+            entry.required = true;
+        if (parameter.attrs['Visible'] === 'false')
+            entry.visible = false;
+        results.push(entry);
+    }
+    return results;
+}
+/** One instruction's local tags, in written order. */
+function aoiLocalTags(aoi) {
+    const localTags = firstChild(aoi, 'LocalTags');
+    if (localTags === undefined)
+        return [];
+    const results = [];
+    for (const localTag of elementChildren(localTags, 'LocalTag')) {
+        const entry = {
+            name: optionalAttribute(localTag, 'Name', ''),
+            dataType: optionalAttribute(localTag, 'DataType', ''),
+        };
+        const description = descriptionOf(localTag);
+        if (description !== '')
+            entry.description = description;
+        results.push(entry);
+    }
+    return results;
+}
+/** One instruction's internal routines with their bodies decoded. */
+function aoiRoutines(aoi) {
+    const name = optionalAttribute(aoi, 'Name', '');
+    return rawAoiRoutines(aoi).map(routine => routineBody(name, routine));
+}
+/** One instruction's `<Routine>` elements, in written order. */
+function rawAoiRoutines(aoi) {
+    const routines = firstChild(aoi, 'Routines');
+    return routines === undefined ? [] : elementChildren(routines, 'Routine');
+}

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

@@ -0,0 +1,15 @@
+/**
+ * The error a reader raises when the text it was given is not an L5X export.
+ *
+ * A caller distinguishes "this is not a project" from "this is a project whose
+ * answer is empty": the reference parser raises for the former and returns an
+ * empty result for the latter. The message names the offending fact — the root
+ * element it found, or the element it could not — so a caller can report it
+ * without re-reading the file.
+ */
+export declare class L5xParseError extends Error {
+    /**
+     * @param message - What was wrong with the text, in the terms the export itself uses.
+     */
+    constructor(message: string);
+}

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

@@ -0,0 +1,18 @@
+/**
+ * The error a reader raises when the text it was given is not an L5X export.
+ *
+ * A caller distinguishes "this is not a project" from "this is a project whose
+ * answer is empty": the reference parser raises for the former and returns an
+ * empty result for the latter. The message names the offending fact — the root
+ * element it found, or the element it could not — so a caller can report it
+ * without re-reading the file.
+ */
+export class L5xParseError extends Error {
+    /**
+     * @param message - What was wrong with the text, in the terms the export itself uses.
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'L5xParseError';
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * The parsed-document seam: parse a Studio 5000 `.l5x` export, then read it.
+ *
+ * A consumer parses once and asks as many questions as it needs, because every
+ * read is pure over the parsed document and none of them touches XML again. The
+ * XML layer and the readers stay behind this module: a consumer names a
+ * document, a scope, or a pattern, never an element.
+ */
+export { L5xParseError } from './errors.ts';
+export type { L5xAoiDefinition, L5xAoiInfo, L5xAoiLocalTag, L5xAoiParameter, L5xAlarm, L5xControllerSummary, L5xDocument, L5xDiagramNode, L5xModule, L5xProgram, L5xProjectSummary, L5xRoutine, L5xRoutineBody, L5xRoutineInfo, L5xRung, L5xSymbolReference, L5xSymbolUsage, L5xTag, L5xTask, L5xUdt, L5xUdtMember, } from './types.ts';
+export { controllerElementOf, loadL5x } from './parse.ts';
+export { loadProject } from './project.ts';
+export { getAoi, getAois, listAois } from './aois.ts';
+export { getRoutine, listRoutines } from './routines.ts';
+export { findTag, listTags } from './tags.ts';
+export { getUdt, listUdtNames } from './udts.ts';
+export { listModules } from './modules.ts';
+export { searchLogic } from './xref.ts';
+/** The literal a health check returns. */
+export declare const PING_RESULT = "pong";

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

@@ -0,0 +1,19 @@
+/**
+ * The parsed-document seam: parse a Studio 5000 `.l5x` export, then read it.
+ *
+ * A consumer parses once and asks as many questions as it needs, because every
+ * read is pure over the parsed document and none of them touches XML again. The
+ * XML layer and the readers stay behind this module: a consumer names a
+ * document, a scope, or a pattern, never an element.
+ */
+export { L5xParseError } from "./errors.js";
+export { controllerElementOf, loadL5x } from "./parse.js";
+export { loadProject } from "./project.js";
+export { getAoi, getAois, listAois } from "./aois.js";
+export { getRoutine, listRoutines } from "./routines.js";
+export { findTag, listTags } from "./tags.js";
+export { getUdt, listUdtNames } from "./udts.js";
+export { listModules } from "./modules.js";
+export { searchLogic } from "./xref.js";
+/** The literal a health check returns. */
+export const PING_RESULT = 'pong';

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

@@ -0,0 +1,37 @@
+/**
+ * Controller-level elements shared by the readers that scan the export.
+ *
+ * A reader asks for the controller element or for the program elements under
+ * it; the two navigation steps live here so the readers do not each restate
+ * where the export keeps programs and controller-scoped tags.
+ */
+import { type XmlElement } from './xml.ts';
+/** The root element's tag name in a Studio 5000 export. */
+export declare const L5X_ROOT_TAG = "RSLogix5000Content";
+/**
+ * The `<Controller>` element of a parsed export.
+ *
+ * @param root - The document element.
+ * @returns The controller element.
+ * @throws L5xParseError When the document has no controller.
+ */
+export declare function controllerElement(root: XmlElement): XmlElement;
+/**
+ * The `<Program>` elements the controller owns.
+ *
+ * @param controller - The controller element.
+ * @returns Program elements, in written order.
+ */
+export declare function programElements(controller: XmlElement): readonly XmlElement[];
+/**
+ * A tag element's description: the `Description` attribute if it is non-empty,
+ * otherwise the `<Description>` child element's trimmed text.
+ *
+ * The attribute wins because the reference parser reads it first, and an empty
+ * attribute is treated as absent so a simplified export that writes the child
+ * form still yields its text.
+ *
+ * @param element - The element carrying the description.
+ * @returns The description, or an empty string when there is none.
+ */
+export declare function descriptionOf(element: XmlElement): string;

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

@@ -0,0 +1,54 @@
+/**
+ * Controller-level elements shared by the readers that scan the export.
+ *
+ * A reader asks for the controller element or for the program elements under
+ * it; the two navigation steps live here so the readers do not each restate
+ * where the export keeps programs and controller-scoped tags.
+ */
+import { firstChild, elementChildren, nodeText, presentAttribute } from "./xml.js";
+import { L5xParseError } from "./errors.js";
+/** The root element's tag name in a Studio 5000 export. */
+export const L5X_ROOT_TAG = 'RSLogix5000Content';
+/**
+ * The `<Controller>` element of a parsed export.
+ *
+ * @param root - The document element.
+ * @returns The controller element.
+ * @throws L5xParseError When the document has no controller.
+ */
+export function controllerElement(root) {
+    const controller = firstChild(root, 'Controller');
+    if (controller === undefined)
+        throw new L5xParseError('No <Controller> element found');
+    return controller;
+}
+/**
+ * The `<Program>` elements the controller owns.
+ *
+ * @param controller - The controller element.
+ * @returns Program elements, in written order.
+ */
+export function programElements(controller) {
+    const programs = firstChild(controller, 'Programs');
+    return programs === undefined ? [] : elementChildren(programs, 'Program');
+}
+/**
+ * A tag element's description: the `Description` attribute if it is non-empty,
+ * otherwise the `<Description>` child element's trimmed text.
+ *
+ * The attribute wins because the reference parser reads it first, and an empty
+ * attribute is treated as absent so a simplified export that writes the child
+ * form still yields its text.
+ *
+ * @param element - The element carrying the description.
+ * @returns The description, or an empty string when there is none.
+ */
+export function descriptionOf(element) {
+    const declared = presentAttribute(element, 'Description');
+    if (declared !== undefined)
+        return declared;
+    const child = firstChild(element, 'Description');
+    if (child === undefined)
+        return '';
+    return (nodeText(child) ?? '').trim();
+}

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

@@ -0,0 +1,24 @@
+/**
+ * I/O module reader.
+ *
+ * A module's slot is its first port's `Address`: that is what the export writes
+ * for a chassis-mounted module, and it is the value an operator reads off the
+ * chassis. A module the controller does not own directly names its parent
+ * instead, and an empty parent means the controller itself.
+ */
+import type { L5xDocument, L5xModule } from './types.ts';
+import { type XmlElement } from './xml.ts';
+/**
+ * List the controller's I/O modules.
+ *
+ * @param document - The parsed project.
+ * @returns One entry per module, in written order.
+ */
+export declare function listModules(document: L5xDocument): readonly L5xModule[];
+/**
+ * Read every I/O module of a controller.
+ *
+ * @param controller - The controller element.
+ * @returns The modules, in written order.
+ */
+export declare function buildModules(controller: XmlElement): readonly L5xModule[];

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

@@ -0,0 +1,55 @@
+/**
+ * I/O module reader.
+ *
+ * A module's slot is its first port's `Address`: that is what the export writes
+ * for a chassis-mounted module, and it is the value an operator reads off the
+ * chassis. A module the controller does not own directly names its parent
+ * instead, and an empty parent means the controller itself.
+ */
+import { controllerElementOf } from "./parse.js";
+import { descriptionOf } from "./module.js";
+import { elementChildren, firstChild, optionalAttribute } from "./xml.js";
+/**
+ * List the controller's I/O modules.
+ *
+ * @param document - The parsed project.
+ * @returns One entry per module, in written order.
+ */
+export function listModules(document) {
+    return buildModules(controllerElementOf(document));
+}
+/**
+ * Read every I/O module of a controller.
+ *
+ * @param controller - The controller element.
+ * @returns The modules, in written order.
+ */
+export function buildModules(controller) {
+    const modules = firstChild(controller, 'Modules');
+    if (modules === undefined)
+        return [];
+    return elementChildren(modules, 'Module').map(parseModule);
+}
+/**
+ * One module entry.
+ *
+ * @param module - The `<Module>` element.
+ * @returns The module entry.
+ */
+function parseModule(module) {
+    const entry = {
+        name: optionalAttribute(module, 'Name', ''),
+        catalogNumber: optionalAttribute(module, 'CatalogNumber', ''),
+        parentModule: optionalAttribute(module, 'ParentModule', ''),
+    };
+    const description = descriptionOf(module);
+    if (description !== '')
+        entry.description = description;
+    const ports = firstChild(module, 'Ports');
+    const port = ports === undefined ? undefined : firstChild(ports, 'Port');
+    if (port !== undefined)
+        entry.slot = optionalAttribute(port, 'Address', '');
+    if (module.attrs['Inhibited'] === 'true')
+        entry.inhibited = true;
+    return entry;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Parse — turn an `.l5x` export into the document every reader answers from.
+ *
+ * Parsing is eager and total: one pass builds the controller summary, programs,
+ * tasks, routines, tags, types, instructions, and modules, so a later read never
+ * re-walks the XML and the same text always yields the same entries. Building
+ * everything up front is what lets a caller parse once and ask many questions.
+ */
+import type { L5xDocument } from './types.ts';
+import { type XmlElement } from './xml.ts';
+/**
+ * Parse a Studio 5000 L5X export.
+ *
+ * @param xml - The export's text.
+ * @returns The parsed document, with every reader's answer already built.
+ * @throws L5xParseError When the text is not well-formed XML, when its root
+ * element is not `<RSLogix5000Content>`, or when it has no `<Controller>`.
+ */
+export declare function loadL5x(xml: string): L5xDocument;
+/**
+ * The document element behind a parsed document.
+ *
+ * The document reports a controller *summary*, so a reader that walks the XML
+ * asks for the element here rather than re-parsing the export. A consumer needs
+ * this only to reach an element-level reader; every document-level read answers
+ * from the parsed document alone.
+ *
+ * @param document - A document from {@link loadL5x}.
+ * @returns That document's controller element.
+ * @throws L5xParseError When the document was not produced by {@link loadL5x}.
+ */
+export declare function controllerElementOf(document: L5xDocument): XmlElement;

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

@@ -0,0 +1,116 @@
+/**
+ * Parse — turn an `.l5x` export into the document every reader answers from.
+ *
+ * Parsing is eager and total: one pass builds the controller summary, programs,
+ * tasks, routines, tags, types, instructions, and modules, so a later read never
+ * re-walks the XML and the same text always yields the same entries. Building
+ * everything up front is what lets a caller parse once and ask many questions.
+ */
+import { L5xParseError } from "./errors.js";
+import { controllerElement, descriptionOf, programElements, L5X_ROOT_TAG } from "./module.js";
+import { documentRoot, elementChildren, firstChild, optionalAttribute, parseXml } from "./xml.js";
+import { buildRoutines } from "./routines.js";
+import { buildTags } from "./tags.js";
+import { buildUdts } from "./udts.js";
+import { buildAois } from "./aois.js";
+import { buildModules } from "./modules.js";
+/** Controller elements of documents already parsed, so a reader can walk them. */
+const controllerElements = new WeakMap();
+/**
+ * Parse a Studio 5000 L5X export.
+ *
+ * @param xml - The export's text.
+ * @returns The parsed document, with every reader's answer already built.
+ * @throws L5xParseError When the text is not well-formed XML, when its root
+ * element is not `<RSLogix5000Content>`, or when it has no `<Controller>`.
+ */
+export function loadL5x(xml) {
+    const root = documentRoot(parseXml(xml));
+    if (root.name !== L5X_ROOT_TAG) {
+        throw new L5xParseError(`Not an L5X file (root element is <${root.name}>, expected <${L5X_ROOT_TAG}>)`);
+    }
+    const controller = controllerElement(root);
+    const document = {
+        controller: controllerSummary(controller),
+        programs: buildPrograms(controller),
+        tasks: buildTasks(controller),
+        routines: buildRoutines(controller),
+        tags: buildTags(controller),
+        udts: buildUdts(controller),
+        aois: buildAois(controller),
+        modules: buildModules(controller),
+        alarms: buildAlarms(controller),
+    };
+    controllerElements.set(document, controller);
+    return document;
+}
+function buildAlarms(controller) {
+    const results = [];
+    const visit = (element) => {
+        if (element.name === 'Alarm' || element.name === 'TagBasedAlarm') {
+            results.push({ name: optionalAttribute(element, 'Name', ''), kind: element.name, description: descriptionOf(element) });
+        }
+        for (const child of element.children)
+            if ('attrs' in child)
+                visit(child);
+    };
+    visit(controller);
+    return results;
+}
+/**
+ * The document element behind a parsed document.
+ *
+ * The document reports a controller *summary*, so a reader that walks the XML
+ * asks for the element here rather than re-parsing the export. A consumer needs
+ * this only to reach an element-level reader; every document-level read answers
+ * from the parsed document alone.
+ *
+ * @param document - A document from {@link loadL5x}.
+ * @returns That document's controller element.
+ * @throws L5xParseError When the document was not produced by {@link loadL5x}.
+ */
+export function controllerElementOf(document) {
+    const controller = controllerElements.get(document);
+    if (controller === undefined)
+        throw new L5xParseError('Not a parsed document: no controller element');
+    return controller;
+}
+/** The controller's own metadata. */
+function controllerSummary(controller) {
+    return {
+        name: optionalAttribute(controller, 'Name', ''),
+        processorType: optionalAttribute(controller, 'ProcessorType', ''),
+        description: descriptionOf(controller),
+        majorRev: optionalAttribute(controller, 'MajorRev', ''),
+        minorRev: optionalAttribute(controller, 'MinorRev', ''),
+    };
+}
+/** The controller's programs. */
+function buildPrograms(controller) {
+    return programElements(controller).map(program => ({
+        name: optionalAttribute(program, 'Name', ''),
+        mainRoutine: optionalAttribute(program, 'MainRoutineName', ''),
+        description: descriptionOf(program),
+    }));
+}
+/** The controller's tasks and what each schedules. */
+function buildTasks(controller) {
+    const tasks = firstChild(controller, 'Tasks');
+    if (tasks === undefined)
+        return [];
+    return elementChildren(tasks, 'Task').map(task => ({
+        name: optionalAttribute(task, 'Name', ''),
+        type: optionalAttribute(task, 'Type', ''),
+        rate: optionalAttribute(task, 'Rate', ''),
+        priority: optionalAttribute(task, 'Priority', ''),
+        description: descriptionOf(task),
+        programs: scheduledPrograms(task),
+    }));
+}
+/** The program names one task schedules. */
+function scheduledPrograms(task) {
+    const scheduled = firstChild(task, 'ScheduledPrograms');
+    if (scheduled === undefined)
+        return [];
+    return elementChildren(scheduled, 'ScheduledProgram').map(program => optionalAttribute(program, 'Name', ''));
+}

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

@@ -0,0 +1,15 @@
+/**
+ * The project listing — the controller summary one call returns.
+ *
+ * The summary is the entry point a caller uses before deciding what to ask
+ * next, so it carries the counts and the names rather than the entries: a
+ * project with hundreds of tags and types still answers in one small value.
+ */
+import type { L5xDocument, L5xProjectSummary } from './types.ts';
+/**
+ * Summarize a parsed project.
+ *
+ * @param document - The parsed document.
+ * @returns The listing, with counts and names rather than the entries themselves.
+ */
+export declare function loadProject(document: L5xDocument): L5xProjectSummary;

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

@@ -0,0 +1,31 @@
+/**
+ * The project listing — the controller summary one call returns.
+ *
+ * The summary is the entry point a caller uses before deciding what to ask
+ * next, so it carries the counts and the names rather than the entries: a
+ * project with hundreds of tags and types still answers in one small value.
+ */
+/**
+ * Summarize a parsed project.
+ *
+ * @param document - The parsed document.
+ * @returns The listing, with counts and names rather than the entries themselves.
+ */
+export function loadProject(document) {
+    const udts = document.udts.map(udt => udt.name);
+    const aois = document.aois.map(aoi => aoi.name);
+    return {
+        controller: document.controller.name,
+        processorType: document.controller.processorType,
+        description: document.controller.description,
+        firmware: `${document.controller.majorRev}.${document.controller.minorRev}`,
+        programs: document.programs,
+        tasks: document.tasks,
+        udtCount: udts.length,
+        udts,
+        aoiCount: aois.length,
+        aois,
+        moduleCount: document.modules.length,
+        tagCount: document.tags.length,
+    };
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Routine reader — ladder as NeutralText with rung comments, Structured Text
+ * as its lines.
+ *
+ * A ladder rung is returned as the compact NeutralText the export already
+ * stores, e.g. `XIC(Motor_Start)XIO(Motor_Fault)OTE(Motor_Run);`, which is what
+ * makes one rung a single readable line instead of its graphical XML. Any other
+ * routine language is reported by name rather than decomposed.
+ */
+import type { L5xDocument, L5xRoutine, L5xRoutineInfo, L5xRung } from './types.ts';
+import { type XmlElement } from './xml.ts';
+/**
+ * List routines with the size of each body.
+ *
+ * The listing names the program, so a caller can pass the name back to
+ * {@link getRoutine}. Only the count for the routine's own language is
+ * reported, which is why at most one count is ever present.
+ *
+ * @param document - The parsed project.
+ * @param program - Program name to restrict to; empty or omitted keeps every program.
+ * @returns One entry per routine, in written order.
+ */
+export declare function listRoutines(document: L5xDocument, program?: string): readonly L5xRoutineInfo[];
+/**
+ * Read one routine's body.
+ *
+ * @param document - The parsed project.
+ * @param program - Program holding the routine.
+ * @param routineName - Routine name.
+ * @returns The routine, or undefined when that program has no such routine.
+ */
+export declare function getRoutine(document: L5xDocument, program: string, routineName: string): L5xRoutine | undefined;
+/**
+ * Read every program's routines of a controller.
+ *
+ * @param controller - The controller element.
+ * @returns The routines, in program then written order.
+ */
+export declare function buildRoutines(controller: XmlElement): readonly L5xRoutine[];
+/**
+ * Decode one routine element's body.
+ *
+ * Add-on instructions read their internal routines through this, so an AOI's
+ * ladder and Structured Text are decoded exactly as a program's are.
+ *
+ * @param owner - Program or add-on instruction the routine belongs to.
+ * @param routine - The `<Routine>` element.
+ * @returns The routine with its body decoded.
+ */
+export declare function routineBody(owner: string, routine: XmlElement): L5xRoutine;
+/**
+ * The numbered lines of a Structured Text body.
+ *
+ * An empty body has no lines: the reader joins the export's lines with `\n`, so
+ * a body of no lines and a body of one empty line both read as `''`, and the
+ * export's own line count is what a listing reports.
+ *
+ * @param code - A Structured Text body.
+ * @returns One entry per line, numbered from zero in body order.
+ */
+export declare function splitLines(code: string): readonly {
+    readonly number: number;
+    readonly text: string;
+}[];
+/**
+ * One ladder routine's rungs, as NeutralText with their comments.
+ *
+ * @param routine - The `<Routine>` element of a ladder routine.
+ * @returns One entry per rung, in written order.
+ */
+export declare function decodeRungs(routine: XmlElement): readonly L5xRung[];