@aryacode/dsh-engineering 0.5.0 → 0.7.0

package/vendor/l5x/lib/engine/change-set.js

@@ -9,12 +9,13 @@ import { uniqueRegion, xmlRegions } from "./xml-regions.js";
 /** Scalar types the plugin can create with a literal initial value. */
 const SCALAR_TYPES = new Set(['BOOL', 'SINT', 'INT', 'DINT', 'LINT', 'USINT', 'UINT', 'UDINT', 'ULINT', 'REAL', 'LREAL']);
 /** Operation names accepted by a version-1 change set. */
-const SUPPORTED_OPERATIONS = ['replace_rung', 'insert_rung', 'delete_rung', 'replace_st', 'add_routine', 'add_tag', 'set_tag_description', 'add_udt_member', 'set_udt_description', 'set_udt_member_description'];
+const SUPPORTED_OPERATIONS = ['replace_rung', 'insert_rung', 'delete_rung', 'set_rung_comment', 'replace_st', 'add_routine', 'add_tag', 'set_tag_description', 'add_udt_member', 'set_udt_description', 'set_udt_member_description'];
 /** Compact contract returned with validation errors and embedded in tool descriptions. */
 export const CHANGE_SET_HELP = `Operations (each also needs "operation"):
-replace_rung {program,routine,rung,text}
-insert_rung {program,routine,rung,text,before_rung?}
+replace_rung {program,routine,rung,text,comment?}
+insert_rung {program,routine,rung,text,before_rung?,comment?}
 delete_rung {program,routine,rung}
+set_rung_comment {program,routine,rung,comment}
 replace_st {program,routine,code}
 add_routine {program,name,language:"RLL"|"ST",code}
 add_tag {scope,name,data_type,description,value? scalar, dimensions? "4 2", external_access? "Read/Write"|"Read Only"|"None"}
@@ -104,17 +105,21 @@ function parseOne(value, declaredTypes) {
         case 'replace_rung':
         case 'insert_rung':
         case 'delete_rung': {
-            fields(row, row.operation === 'delete_rung' ? ['operation', 'program', 'routine', 'rung'] : row.operation === 'insert_rung' ? ['operation', 'program', 'routine', 'rung', 'text', 'before_rung'] : ['operation', 'program', 'routine', 'rung', 'text']);
+            fields(row, row.operation === 'delete_rung' ? ['operation', 'program', 'routine', 'rung'] : row.operation === 'insert_rung' ? ['operation', 'program', 'routine', 'rung', 'text', 'before_rung', 'comment'] : ['operation', 'program', 'routine', 'rung', 'text', 'comment']);
             const selected = { program: identifier(row, 'program'), routine: identifier(row, 'routine'), rung: integer(row, 'rung') };
             if (row.operation === 'delete_rung')
                 return { operation: row.operation, ...selected };
             const source = text(row, 'text');
             if (parseLadder(source).issues.length > 0)
                 throw new EngineeringError('INVALID_LADDER', 'Rung contains malformed or unsupported NeutralText structure');
+            const comment = row.comment === undefined ? {} : { comment: text(row, 'comment') };
             if (row.operation === 'replace_rung')
-                return { operation: row.operation, ...selected, text: source };
-            return { operation: row.operation, ...selected, text: source, ...(row.before_rung === undefined ? {} : { before_rung: integer(row, 'before_rung') }) };
+                return { operation: row.operation, ...selected, text: source, ...comment };
+            return { operation: row.operation, ...selected, text: source, ...comment, ...(row.before_rung === undefined ? {} : { before_rung: integer(row, 'before_rung') }) };
         }
+        case 'set_rung_comment':
+            fields(row, ['operation', 'program', 'routine', 'rung', 'comment']);
+            return { operation: row.operation, program: identifier(row, 'program'), routine: identifier(row, 'routine'), rung: integer(row, 'rung'), comment: text(row, 'comment') };
         case 'replace_st':
             fields(row, ['operation', 'program', 'routine', 'code']);
             return { operation: row.operation, program: identifier(row, 'program'), routine: identifier(row, 'routine'), code: text(row, 'code') };
@@ -314,7 +319,7 @@ function applyOperation(xml, operation, context) {
     if (operation.operation === 'insert_rung') {
         if (targets.length !== 0)
             throw new EngineeringError('NAME_COLLISION', 'Rung number already exists; no automatic renumbering is performed');
-        const newRung = `<Rung Number="${operation.rung}" Type="N"><Text>${cdata(operation.text)}</Text></Rung>`;
+        const newRung = `<Rung Number="${operation.rung}" Type="N">${commentXml(operation.comment)}<Text>${cdata(operation.text)}</Text></Rung>`;
         if (operation.before_rung === undefined)
             return insert(xml, content, newRung);
         const before = rungs.filter(rung => Number(rung.attributes.Number) === operation.before_rung);
@@ -327,9 +332,29 @@ function applyOperation(xml, operation, context) {
     const target = targets[0];
     if (operation.operation === 'delete_rung')
         return replace(xml, target.start, target.end, '');
+    if (operation.operation === 'set_rung_comment') {
+        return replace(xml, target.start, target.end, rungWith(target, retainedText(xml, target), operation.comment));
+    }
+    if (operation.comment !== undefined) {
+        return replace(xml, target.start, target.end, rungWith(target, `<Text>${cdata(operation.text)}</Text>`, operation.comment));
+    }
     const contentText = uniqueRegion(target.children, 'Text');
     return replace(xml, contentText.start, contentText.end, `<Text>${cdata(operation.text)}</Text>`);
 }
+/** A comment element, or nothing when the comment is cleared. */
+function commentXml(comment) {
+    return comment === undefined || comment === '' ? '' : `<Comment>${cdata(comment)}</Comment>`;
+}
+/** The rung's existing `<Text>` element, verbatim, for a comment-only edit. */
+function retainedText(xml, rung) {
+    const text = rung.children.find(child => child.kind === 'Text');
+    return text === undefined ? '<Text><![CDATA[]]></Text>' : xml.slice(text.start, text.end);
+}
+/** Rebuild one rung element with a comment and a text element. */
+function rungWith(rung, text, comment) {
+    const type = rung.attributes.Type ?? 'N';
+    return `<Rung Number="${rung.attributes.Number}" Type="${type}">${commentXml(comment)}${text}</Rung>`;
+}
 /** Every type name a change may reference: scalars plus declared types. */
 function declaredTypeNames(project) {
     const names = new Set([...SCALAR_TYPES].map(name => name.toLowerCase()));

package/vendor/l5x/lib/engine/documentation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Build the handover documentation bundle for one export.
+ *
+ * Everything here is derived from the parsed project: the generator provides the
+ * structure and the citations, and the narrative prose stays the caller's job.
+ * That split is deliberate — a generated narrative would be an unsourced claim,
+ * while a rung with its number, comment, text and referenced tags is evidence a
+ * reviewer can check in one click.
+ *
+ * The builder is pure: it returns a map of relative path to text and writes
+ * nothing. The tool decides where the folder goes.
+ *
+ * @module dsh-engineering-l5x/engine/documentation
+ */
+import type { ProjectSnapshot } from '../session.ts';
+/** One documentation part a caller can ask for. */
+export type DocumentPart = 'project' | 'io' | 'tags' | 'rungs';
+/** Every part, in the order the files are produced. */
+export declare const DOCUMENT_PARTS: readonly DocumentPart[];
+/** What one generation produced. */
+export interface DocumentBundle {
+    /** Relative path to file text. */
+    readonly files: ReadonlyMap<string, string>;
+    /** Counts a caller can compare with project_overview. */
+    counts: {
+        programs: number;
+        tasks: number;
+        routines: number;
+        rungs: number;
+        comments: number;
+        tags: number;
+        modules: number;
+    };
+    /** Programs and routines the filters excluded. */
+    readonly excluded: {
+        readonly programs: readonly string[];
+        readonly routines: readonly string[];
+    };
+}
+/** Options for one generation. */
+export interface DocumentOptions {
+    /** Parts to produce; defaults to all. */
+    readonly include?: readonly DocumentPart[];
+    /** Restrict to these programs. */
+    readonly programs?: readonly string[];
+    /** Restrict to these routine names. */
+    readonly routines?: readonly string[];
+    /** Most rungs per generated file before a continuation file is written. */
+    readonly rungsPerFile?: number;
+}
+/**
+ * Build the documentation bundle.
+ *
+ * @param project - Open export snapshot.
+ * @param options - Parts, filters and file split.
+ * @returns Files to write, counts, and what the filters excluded.
+ */
+export declare function buildDocumentation(project: ProjectSnapshot, options?: DocumentOptions): DocumentBundle;

package/vendor/l5x/lib/engine/documentation.js

@@ -0,0 +1,237 @@
+/**
+ * Build the handover documentation bundle for one export.
+ *
+ * Everything here is derived from the parsed project: the generator provides the
+ * structure and the citations, and the narrative prose stays the caller's job.
+ * That split is deliberate — a generated narrative would be an unsourced claim,
+ * while a rung with its number, comment, text and referenced tags is evidence a
+ * reviewer can check in one click.
+ *
+ * The builder is pure: it returns a map of relative path to text and writes
+ * nothing. The tool decides where the folder goes.
+ *
+ * @module dsh-engineering-l5x/engine/documentation
+ */
+import { L5xError } from "../core/errors.js";
+import { getRoutine, listRoutines } from "../model/routines.js";
+import { aliasesOf } from "./configuration.js";
+import { parseLadder } from "./logic-syntax.js";
+import { resolveTag } from "./tag-resolution.js";
+/** Every part, in the order the files are produced. */
+export const DOCUMENT_PARTS = ['project', 'io', 'tags', 'rungs'];
+/** CSV cell with quoting when the value needs it. */
+function cell(value) {
+    const text = value === undefined || value === null ? '' : String(value);
+    return /[",\n\r]/u.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+/** One CSV line. */
+function line(...values) {
+    return `${values.map(cell).join(',')}\n`;
+}
+/** A markdown table row. */
+function mdRow(...values) {
+    return `| ${values.map(value => String(value ?? '').replaceAll('|', '\\|').replaceAll('\n', ' ')).join(' | ')} |\n`;
+}
+/** Every instruction name in one rung, branches included. */
+function instructionsOf(nodes, out = new Set()) {
+    for (const node of nodes) {
+        if (node.kind === 'instruction')
+            out.add(node.name.toUpperCase());
+        else
+            for (const path of node.paths)
+                instructionsOf(path, out);
+    }
+    return out;
+}
+/** Tags a rung mentions, resolved through the export; instruction names excluded. */
+function tagsOf(document, rung) {
+    const parsed = parseLadder(rung.text);
+    const instructions = instructionsOf(parsed.nodes);
+    for (const aoi of document.aois)
+        instructions.add(aoi.name.toUpperCase());
+    const found = new Set();
+    for (const match of rung.text.matchAll(/[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+|\[[^\]]*\])*/gu)) {
+        const text = match[0];
+        if (instructions.has(text.toUpperCase()))
+            continue;
+        const resolution = resolveTag(document, 'controller', text);
+        if (resolution.resolved)
+            found.add(resolution.canonical ?? text);
+    }
+    return [...found];
+}
+/** A tag's alias target, for the CSV only. */
+function aliasTarget(document, tag) {
+    return aliasesOf(document).get(`${tag.scope}::${tag.name}`) ?? '';
+}
+/** The tags CSV every declared tag appears in. */
+function tagsCsv(document) {
+    let text = line('scope', 'name', 'data_type', 'description', 'alias_for', 'dimensions', 'external_access');
+    for (const tag of document.tags) {
+        const record = tag;
+        text += line(tag.scope, tag.name, tag.dataType, tag.description ?? '', aliasTarget(document, tag), record.dimensions ?? '', tag.externalAccess ?? '');
+    }
+    return text;
+}
+/**
+ * The Studio import shape: `Tag Name,Description`.
+ *
+ * A program-scoped tag is written `Program:Name` so a duplicate name across two
+ * programs cannot silently overwrite one of them on import. Verify the template
+ * against the installed Studio help before relying on it for a bulk import.
+ */
+function tagsStudioCsv(document) {
+    let text = line('Tag Name', 'Description');
+    for (const tag of document.tags) {
+        const name = tag.scope === 'controller' ? tag.name : `${tag.scope}:${tag.name}`;
+        text += line(name, tag.description ?? '');
+    }
+    return text;
+}
+/** The I/O list: modules and the tags that look like module data. */
+function ioFiles(document) {
+    const io = document.tags.filter(tag => tag.name.includes(':'));
+    let markdown = '# I/O list\n\n';
+    markdown += `${document.modules.length} module(s); ${io.length} tag(s) look like module data (a colon in the name).\n\n`;
+    markdown += '| Module | Catalog | Slot | Parent | Inhibited | Description |\n|---|---|---|---|---|---|\n';
+    for (const module of document.modules) {
+        markdown += mdRow(module.name, module.catalogNumber, module.slot ?? '', module.parentModule, module.inhibited === true, module.description ?? '');
+    }
+    markdown += `\nModule-data tags: ${io.map(tag => tag.name).join(', ') || 'none'}.\n`;
+    let csv = line('name', 'catalog_number', 'slot', 'parent_module', 'inhibited', 'description');
+    for (const module of document.modules)
+        csv += line(module.name, module.catalogNumber, module.slot ?? '', module.parentModule, module.inhibited === true, module.description ?? '');
+    return { markdown, csv };
+}
+/** The project summary: identity, tasks, programs, counts, coverage. */
+function projectMarkdown(project, counts) {
+    const document = project.document;
+    const { controller } = document;
+    let text = `# ${controller.name} project documentation\n\n`;
+    text += `Generated from \`${project.path}\` (sha256 \`${project.sha256.slice(0, 16)}…\`) at ${new Date().toISOString()}.\n\n`;
+    text += `- Processor: ${controller.processorType}\n- Revision: ${document.controller.majorRev}.${document.controller.minorRev}\n`;
+    text += `- Export: ${project.exportKind}; parser verification: ${project.verification}\n`;
+    text += `- Programs: ${counts.programs}; tasks: ${counts.tasks}; routines: ${counts.routines}; rungs: ${counts.rungs} (${counts.comments} with comments); tags: ${counts.tags}; modules: ${counts.modules}\n\n`;
+    text += '## Tasks\n\n| Task | Type | Rate (ms) | Priority | Programs |\n|---|---|---|---|---|\n';
+    for (const task of document.tasks)
+        text += mdRow(task.name, task.type, task.rate, task.priority, task.programs.join(', '));
+    text += '\n## Programs\n\n| Program | Main routine | Routines | Description |\n|---|---|---|---|\n';
+    for (const program of document.programs) {
+        const routines = listRoutines(document, program.name);
+        text += mdRow(program.name, program.mainRoutine, routines.length, program.description);
+    }
+    text += '\n## Coverage\n\nThis document is generated from the saved export. It does not prove construction of the program,';
+    text += ' compiled behaviour, runtime behaviour, or anything outside the export (HMI, produced/consumed tags, driver consumers).\n';
+    return text;
+}
+/** Rung skeletons, one markdown file per program (and continuation). */
+function rungFiles(project, options) {
+    const files = new Map();
+    const document = project.document;
+    const programs = options.programs ?? document.programs.map(program => program.name);
+    for (const programName of programs) {
+        const program = document.programs.find(entry => entry.name === programName);
+        if (program === undefined)
+            continue;
+        let section = `# ${programName} — rung documentation\n\nProgram main routine: ${program.mainRoutine || 'not declared'}. ${program.description || 'No program description.'}\n`;
+        let part = 1;
+        let inFile = 0;
+        let headingWritten = false;
+        for (const info of listRoutines(document, programName)) {
+            if (options.routines !== undefined && !options.routines.includes(info.name))
+                continue;
+            const routine = getRoutine(document, programName, info.name);
+            if (routine === undefined || routine.body.type !== 'RLL')
+                continue;
+            section += `\n## ${info.name}\n\n${info.description || 'No routine description.'}\n`;
+            for (const rung of routine.body.rungs) {
+                const instructions = [...instructionsOf(parseLadder(rung.text).nodes)].join(', ');
+                const tags = tagsOf(document, rung);
+                section += `\n### Rung ${rung.number}\n\n`;
+                if (rung.comment !== undefined)
+                    section += `**Comment:** ${rung.comment.replaceAll('\n', '\n> ')}\n\n`;
+                section += `\`\`\`\n${rung.text}\n\`\`\`\n\n`;
+                section += `Instructions: ${instructions || 'none parsed'}.\n`;
+                if (tags.length > 0)
+                    section += `Tags: ${tags.join(', ')}.\n`;
+                inFile += 1;
+                if (inFile >= options.perFile) {
+                    files.set(part === 1 ? `rungs/${programName}.md` : `rungs/${programName}-${part}.md`, section);
+                    part += 1;
+                    inFile = 0;
+                    headingWritten = true;
+                    section = `# ${programName} — rung documentation (continued)\n`;
+                }
+            }
+        }
+        if (inFile > 0 || !headingWritten)
+            files.set(part === 1 ? `rungs/${programName}.md` : `rungs/${programName}-${part}.md`, section);
+    }
+    return files;
+}
+/**
+ * Build the documentation bundle.
+ *
+ * @param project - Open export snapshot.
+ * @param options - Parts, filters and file split.
+ * @returns Files to write, counts, and what the filters excluded.
+ */
+export function buildDocumentation(project, options = {}) {
+    const document = project.document;
+    const include = new Set(options.include ?? DOCUMENT_PARTS);
+    const programs = options.programs === undefined ? undefined : [...options.programs];
+    const routines = options.routines === undefined ? undefined : [...options.routines];
+    if (programs !== undefined) {
+        const unknown = programs.filter(name => !document.programs.some(program => program.name === name));
+        if (unknown.length > 0)
+            throw new L5xError('COMPONENT_NOT_FOUND', `No program named ${unknown.join(', ')}.`, 'Call list_components kind="program" for the declared names.', document.programs.map(program => program.name).slice(0, 5));
+    }
+    const counts = {
+        programs: programs?.length ?? document.programs.length,
+        tasks: document.tasks.length,
+        routines: 0,
+        rungs: 0,
+        comments: 0,
+        tags: document.tags.length,
+        modules: document.modules.length,
+    };
+    for (const program of document.programs) {
+        if (programs !== undefined && !programs.includes(program.name))
+            continue;
+        for (const routine of listRoutines(document, program.name)) {
+            if (routines !== undefined && !routines.includes(routine.name))
+                continue;
+            counts.routines += 1;
+            const body = getRoutine(document, program.name, routine.name);
+            if (body !== undefined && body.body.type === 'RLL') {
+                counts.rungs += body.body.rungs.length;
+                counts.comments += body.body.rungs.filter(rung => rung.comment !== undefined).length;
+            }
+        }
+    }
+    const files = new Map();
+    if (include.has('project'))
+        files.set('PROJECT.md', projectMarkdown(project, counts));
+    if (include.has('io')) {
+        const io = ioFiles(document);
+        files.set('io.md', io.markdown);
+        files.set('io.csv', io.csv);
+    }
+    if (include.has('tags')) {
+        files.set('tags.csv', tagsCsv(document));
+        files.set('tags-studio.csv', tagsStudioCsv(document));
+    }
+    if (include.has('rungs')) {
+        const perFile = Math.max(1, options.rungsPerFile ?? 200);
+        for (const [path, text] of rungFiles(project, { programs, routines, perFile }))
+            files.set(path, text);
+    }
+    return {
+        files,
+        counts,
+        excluded: {
+            programs: programs === undefined ? [] : document.programs.map(program => program.name).filter(name => !programs.includes(name)),
+            routines: document.routines.map(routine => routine.name).filter(name => routines !== undefined && !routines.includes(name)),
+        },
+    };
+}

package/vendor/l5x/lib/engine/instructions.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The instruction catalog the ladder composer validates against.
+ *
+ * Logix has no instruction dictionary inside an L5X export, so a generated rung
+ * could previously name any identifier and still parse. This table is the
+ * contract: an instruction, its operand slots and the kind each slot accepts.
+ *
+ * The set covers what engineering programs actually use — measured against a
+ * 1279-tag, 860-rung project — rather than every instruction the vendor ships.
+ * An unknown name is refused with the nearest catalog names; an AOI declared by
+ * the project is accepted separately, because its pins live in the export.
+ *
+ * @module dsh-engineering-l5x/engine/instructions
+ */
+/** What one operand slot accepts. */
+export type OperandKind = 'BOOL' | 'NUMBER' | 'ANY' | 'TIMER' | 'COUNTER';
+/** One operand slot. */
+export interface InstructionOperand {
+    /** Slot name as the programming manual presents it. */
+    readonly name: string;
+    /** What the slot accepts. */
+    readonly kind: OperandKind;
+    /** True when the instruction accepts the slot but does not require it. */
+    readonly optional?: boolean;
+}
+/** One catalogued instruction. */
+export interface InstructionInfo {
+    /** Instruction mnemonic, upper case. */
+    readonly name: string;
+    /** Grouping shown by the listing tool. */
+    readonly category: string;
+    /** One line on what the instruction does. */
+    readonly summary: string;
+    /** Operand slots in written order. */
+    readonly operands: readonly InstructionOperand[];
+}
+/** Scalar data types the composer treats as numbers. */
+export declare const NUMERIC_TYPES: ReadonlySet<string>;
+/** Timer data types. */
+export declare const TIMER_TYPES: ReadonlySet<string>;
+/** Counter data types. */
+export declare const COUNTER_TYPES: ReadonlySet<string>;
+/** The catalog, in category order. */
+export declare const INSTRUCTIONS: readonly InstructionInfo[];
+/** The catalog entry for one mnemonic, following the alias table. */
+export declare function instructionByName(name: string): InstructionInfo | undefined;
+/** The catalog name a caller should use for a mnemonic. */
+export declare function canonicalInstruction(name: string): string;
+/** Up to `limit` catalog names closest to one unknown mnemonic. */
+export declare function nearestInstructions(name: string, limit?: number): readonly string[];

package/vendor/l5x/lib/engine/instructions.js

@@ -0,0 +1,107 @@
+/**
+ * The instruction catalog the ladder composer validates against.
+ *
+ * Logix has no instruction dictionary inside an L5X export, so a generated rung
+ * could previously name any identifier and still parse. This table is the
+ * contract: an instruction, its operand slots and the kind each slot accepts.
+ *
+ * The set covers what engineering programs actually use — measured against a
+ * 1279-tag, 860-rung project — rather than every instruction the vendor ships.
+ * An unknown name is refused with the nearest catalog names; an AOI declared by
+ * the project is accepted separately, because its pins live in the export.
+ *
+ * @module dsh-engineering-l5x/engine/instructions
+ */
+/** Scalar data types the composer treats as numbers. */
+export const NUMERIC_TYPES = new Set(['SINT', 'INT', 'DINT', 'LINT', 'USINT', 'UINT', 'UDINT', 'ULINT', 'REAL', 'LREAL']);
+/** Timer data types. */
+export const TIMER_TYPES = new Set(['TIMER', 'TON', 'TOF', 'RTO']);
+/** Counter data types. */
+export const COUNTER_TYPES = new Set(['COUNTER', 'CTU', 'CTD', 'CTUD']);
+/** Slot helpers kept terse: the table reads as data, not code. */
+const bool = (name = 'Tag') => ({ name, kind: 'BOOL' });
+const num = (name = 'Source') => ({ name, kind: 'NUMBER' });
+/** The catalog, in category order. */
+export const INSTRUCTIONS = [
+    // Contacts and coils
+    { name: 'XIC', category: 'Contacts and coils', summary: 'Examine if closed: true when the BOOL tag is true.', operands: [bool()] },
+    { name: 'XIO', category: 'Contacts and coils', summary: 'Examine if open: true when the BOOL tag is false.', operands: [bool()] },
+    { name: 'OTE', category: 'Contacts and coils', summary: 'Output energize: sets the BOOL tag to the rung condition.', operands: [bool()] },
+    { name: 'OTL', category: 'Contacts and coils', summary: 'Output latch: sets the BOOL tag when the rung is true and holds it.', operands: [bool()] },
+    { name: 'OTU', category: 'Contacts and coils', summary: 'Output unlatch: clears a latched BOOL tag when the rung is true.', operands: [bool()] },
+    { name: 'ONS', category: 'Contacts and coils', summary: 'One shot: true for one scan when the rung goes true.', operands: [{ name: 'Storage', kind: 'BOOL' }] },
+    { name: 'AFI', category: 'Contacts and coils', summary: 'Always false instruction: disables the rung and its outputs.', operands: [] },
+    // Comparison
+    { name: 'EQU', category: 'Comparison', summary: 'Equal: true when source A equals source B.', operands: [num('Source A'), num('Source B')] },
+    { name: 'NEQ', category: 'Comparison', summary: 'Not equal.', operands: [num('Source A'), num('Source B')] },
+    { name: 'GRT', category: 'Comparison', summary: 'Greater than.', operands: [num('Source A'), num('Source B')] },
+    { name: 'GEQ', category: 'Comparison', summary: 'Greater than or equal.', operands: [num('Source A'), num('Source B')] },
+    { name: 'LES', category: 'Comparison', summary: 'Less than.', operands: [num('Source A'), num('Source B')] },
+    { name: 'LEQ', category: 'Comparison', summary: 'Less than or equal.', operands: [num('Source A'), num('Source B')] },
+    { name: 'LIM', category: 'Comparison', summary: 'Limit test: true when the test value lies between the limits.', operands: [num('Low limit'), num('Test'), num('High limit')] },
+    { name: 'CMP', category: 'Comparison', summary: 'Compare: true when the expression is true.', operands: [{ name: 'Expression', kind: 'ANY' }] },
+    // Math
+    { name: 'ADD', category: 'Math', summary: 'Add source A and source B into the destination.', operands: [num('Source A'), num('Source B'), num('Destination')] },
+    { name: 'SUB', category: 'Math', summary: 'Subtract source B from source A into the destination.', operands: [num('Source A'), num('Source B'), num('Destination')] },
+    { name: 'MUL', category: 'Math', summary: 'Multiply source A by source B into the destination.', operands: [num('Source A'), num('Source B'), num('Destination')] },
+    { name: 'DIV', category: 'Math', summary: 'Divide source A by source B into the destination.', operands: [num('Source A'), num('Source B'), num('Destination')] },
+    { name: 'MOD', category: 'Math', summary: 'Remainder of source A divided by source B.', operands: [num('Source A'), num('Source B'), num('Destination')] },
+    { name: 'SQR', category: 'Math', summary: 'Square root of the source into the destination.', operands: [num('Source'), num('Destination')] },
+    { name: 'CPT', category: 'Math', summary: 'Compute an expression into the destination.', operands: [{ name: 'Expression', kind: 'ANY' }, num('Destination')] },
+    // Move
+    { name: 'MOV', category: 'Move', summary: 'Move the source value into the destination.', operands: [num('Source'), num('Destination')] },
+    { name: 'COP', category: 'Move', summary: 'Copy elements from the source to the destination.', operands: [{ name: 'Source', kind: 'ANY' }, { name: 'Destination', kind: 'ANY' }, num('Length')] },
+    { name: 'CLR', category: 'Move', summary: 'Clear the destination to zero.', operands: [num('Destination')] },
+    // Timer and counter
+    { name: 'TON', category: 'Timer and counter', summary: 'Timer on delay: accumulates while the rung is true.', operands: [{ name: 'Timer', kind: 'TIMER' }, num('Preset')] },
+    { name: 'TOF', category: 'Timer and counter', summary: 'Timer off delay: accumulates after the rung goes false.', operands: [{ name: 'Timer', kind: 'TIMER' }, num('Preset')] },
+    { name: 'RTO', category: 'Timer and counter', summary: 'Retentive timer on: accumulates and holds its value.', operands: [{ name: 'Timer', kind: 'TIMER' }, num('Preset')] },
+    { name: 'RES', category: 'Timer and counter', summary: 'Reset a timer or counter structure.', operands: [{ name: 'Structure', kind: 'ANY' }] },
+    { name: 'CTU', category: 'Timer and counter', summary: 'Count up on each false-to-true rung transition.', operands: [{ name: 'Counter', kind: 'COUNTER' }, num('Preset')] },
+    { name: 'CTD', category: 'Timer and counter', summary: 'Count down on each false-to-true rung transition.', operands: [{ name: 'Counter', kind: 'COUNTER' }, num('Preset')] },
+    // Program control
+    { name: 'JSR', category: 'Program control', summary: 'Jump to a subroutine; parameters follow the routine name.', operands: [{ name: 'Routine', kind: 'ANY' }, { name: 'Parameter', kind: 'ANY', optional: true }] },
+    { name: 'RET', category: 'Program control', summary: 'Return from a subroutine.', operands: [] },
+    { name: 'JMP', category: 'Program control', summary: 'Jump to a label in the same routine.', operands: [{ name: 'Label', kind: 'ANY' }] },
+    { name: 'LBL', category: 'Program control', summary: 'Label target for a JMP.', operands: [{ name: 'Label', kind: 'ANY' }] },
+    { name: 'MCR', category: 'Program control', summary: 'Master control relay zone boundary.', operands: [] },
+    // Bit
+    { name: 'AND', category: 'Bit', summary: 'Bitwise AND of two sources into the destination.', operands: [num('Source A'), num('Source B'), num('Destination')] },
+    { name: 'OR', category: 'Bit', summary: 'Bitwise OR of two sources into the destination.', operands: [num('Source A'), num('Source B'), num('Destination')] },
+    { name: 'XOR', category: 'Bit', summary: 'Bitwise exclusive OR of two sources into the destination.', operands: [num('Source A'), num('Source B'), num('Destination')] },
+    { name: 'NOT', category: 'Bit', summary: 'Bitwise complement of the source into the destination.', operands: [num('Source'), num('Destination')] },
+    { name: 'BSL', category: 'Bit', summary: 'Bit shift left through an array.', operands: [{ name: 'Array', kind: 'ANY' }, { name: 'Control', kind: 'ANY' }, num('Length')] },
+    { name: 'BSR', category: 'Bit', summary: 'Bit shift right through an array.', operands: [{ name: 'Array', kind: 'ANY' }, { name: 'Control', kind: 'ANY' }, num('Length')] },
+];
+/** Alias spellings accepted for a catalog name. */
+const ALIASES = { EQ: 'EQU', NE: 'NEQ', GT: 'GRT', GE: 'GEQ', LT: 'LES', LE: 'LEQ', LIMIT: 'LIM', MOVE: 'MOV' };
+/** The catalog entry for one mnemonic, following the alias table. */
+export function instructionByName(name) {
+    const upper = name.toUpperCase();
+    const canonical = ALIASES[upper] ?? upper;
+    return INSTRUCTIONS.find(instruction => instruction.name === canonical);
+}
+/** The catalog name a caller should use for a mnemonic. */
+export function canonicalInstruction(name) {
+    const upper = name.toUpperCase();
+    return ALIASES[upper] ?? upper;
+}
+/** Up to `limit` catalog names closest to one unknown mnemonic. */
+export function nearestInstructions(name, limit = 5) {
+    const upper = name.toUpperCase();
+    const scored = INSTRUCTIONS.map(instruction => {
+        let score = 0;
+        const candidate = instruction.name;
+        for (let index = 0; index < Math.min(candidate.length, upper.length); index += 1) {
+            if (candidate[index] === upper[index])
+                score += 1;
+            else
+                break;
+        }
+        for (const letter of new Set(upper))
+            if (candidate.includes(letter))
+                score += 0.1;
+        return { name: candidate, score };
+    });
+    return scored.sort((left, right) => right.score - left.score).slice(0, limit).map(row => row.name);
+}

package/vendor/l5x/lib/engine/ladder.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Compose one ladder rung from a structure, never from prose.
+ *
+ * The composer is the generation half of the pair: the caller decides the logic,
+ * this module decides the NeutralText. Every instruction is checked against the
+ * catalog (or a declared AOI), every operand against the export, and the emitted
+ * text is re-parsed by the same parser `draft_rung` uses. A rung that fails any
+ * of those never reaches a draft.
+ *
+ * @module dsh-engineering-l5x/engine/ladder
+ */
+import type { ProjectSnapshot } from '../session.ts';
+/** One instruction node. */
+export interface InstructionNode {
+    /** Instruction mnemonic, for example `XIC`. */
+    readonly instr: string;
+    /** Operands in written order. */
+    readonly args?: readonly string[];
+}
+/** A left-to-right sequence of nodes. */
+export interface SeriesNode {
+    /** Nodes evaluated in series. */
+    readonly series: readonly LadderNodeSpec[];
+}
+/** Parallel paths, each a left-to-right sequence. */
+export interface ParallelNode {
+    /** One entry per path. */
+    readonly parallel: readonly (readonly LadderNodeSpec[])[];
+}
+/** One node of the composition tree. */
+export type LadderNodeSpec = InstructionNode | SeriesNode | ParallelNode;
+/** One operand, with what the export says about it. */
+export interface ComposedOperand {
+    /** Operand text as emitted. */
+    readonly text: string;
+    /** Whether the export declares it (false for numeric literals). */
+    readonly resolved: boolean;
+    /** Canonical declaration when it resolves. */
+    readonly canonical?: string;
+    /** Declared data type when it resolves. */
+    readonly data_type?: string;
+}
+/** One composed rung. */
+export interface ComposedRung {
+    /** NeutralText, ready for `draft_rung`. */
+    readonly neutral_text: string;
+    /** Instruction count. */
+    readonly instructions: number;
+    /** Operands in written order. */
+    readonly operands: readonly ComposedOperand[];
+    /** Where the instruction grammar came from. */
+    readonly grounding: 'catalog' | 'aoi' | 'mixed';
+}
+/** A composition result: one rung, or a pattern's pair. */
+export interface ComposedRungs {
+    /** Rungs in evaluation order. */
+    readonly rungs: readonly ComposedRung[];
+    /** Pattern name, when a pattern produced them. */
+    readonly pattern?: string;
+}
+/** Named patterns the composer can expand. */
+export declare const PATTERNS: readonly ["start_stop_latch", "fault_latch", "ton_delay", "interlock"];
+/** One pattern name. */
+export type PatternName = (typeof PATTERNS)[number];
+/**
+ * Compose one rung from a structure tree.
+ *
+ * @param project - Fresh export snapshot the operands are resolved against.
+ * @param spec - The composition tree.
+ * @returns The validated rung.
+ */
+export declare function composeRung(project: ProjectSnapshot, spec: LadderNodeSpec): ComposedRung;
+/** A pattern's named tags, expanded to one or two rungs. */
+export declare function composePattern(project: ProjectSnapshot, pattern: PatternName, args: Readonly<Record<string, unknown>>): ComposedRungs;