@aryacode/dsh-engineering 0.6.0 → 0.7.0

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;

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

@@ -0,0 +1,209 @@
+/**
+ * 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 { L5xError } from "../core/errors.js";
+import { resolveTag } from "./tag-resolution.js";
+import { instructionByName, nearestInstructions, NUMERIC_TYPES, TIMER_TYPES } from "./instructions.js";
+import { parseLadder } from "./logic-syntax.js";
+/** Named patterns the composer can expand. */
+export const PATTERNS = ['start_stop_latch', 'fault_latch', 'ton_delay', 'interlock'];
+const MAX_INSTRUCTIONS = 64;
+const MAX_DEPTH = 16;
+const LITERAL = /^-?(?:\d+\.?\d*|\.\d+)$/u;
+const TAG_TEXT = /^[A-Za-z_][A-Za-z0-9_:.[\]]*$/u;
+/** A numeric literal, which is not a declaration. */
+const isLiteral = (text) => LITERAL.test(text);
+/** A BOOL-ish check for the slot validation below uses this resolved operand. */
+function resolveOperand(document, text) {
+    const direct = resolveTag(document, 'controller', text);
+    if (direct.resolved)
+        return direct;
+    // A rung is written inside a program, so an unqualified program tag is the
+    // ordinary case. Resolve it when exactly one program declares the base name;
+    // two programs declaring it is an ambiguity the caller must settle.
+    const base = text.split(/[.[:]/u)[0] ?? text;
+    const declared = document.tags.filter(tag => tag.name.toUpperCase() === base.toUpperCase());
+    if (declared.length === 1)
+        return resolveTag(document, declared[0].scope, text);
+    if (declared.length > 1) {
+        throw new L5xError('AMBIGUOUS_TAG', `${base} is declared in ${declared.length} scopes.`, 'Declare the tag once, or stage the rung through a routine in the program that owns it.', declared.map(tag => tag.scope));
+    }
+    return direct;
+}
+/** One tag or literal operand, checked against its slot kind. */
+function checkOperand(project, text, kind, seen) {
+    if (isLiteral(text)) {
+        // A literal is a value, not an address: only the slots that take a value accept it.
+        if (kind === 'BOOL')
+            throw new L5xError('INVALID_OPERAND', `${text} is a number where a BOOL tag is required.`, 'Pass a declared BOOL tag.');
+        if (kind === 'TIMER')
+            throw new L5xError('INVALID_OPERAND', `${text} is a number where a timer is required.`, 'Pass a declared TIMER tag.');
+        const operand = { text, resolved: false };
+        seen.push(operand);
+        return operand;
+    }
+    if (!TAG_TEXT.test(text)) {
+        throw new L5xError('INVALID_OPERAND', `"${text}" is not a tag or a number.`, 'Pass a declared tag name, a member path, or a numeric literal; no spaces or quotes.');
+    }
+    const resolution = resolveOperand(project.document, text);
+    if (!resolution.resolved) {
+        const near = project.document.tags
+            .map(tag => tag.name)
+            .filter(name => name.toLowerCase().includes(text.split('.')[0].toLowerCase()))
+            .slice(0, 5);
+        throw new L5xError('TAG_NOT_FOUND', `No tag named "${text}" resolves in this export.`, near.length === 0 ? 'Call list_components kind="tag" to see the declared names.' : 'Retry with one of the candidates, or declare the tag first.', near);
+    }
+    const type = (resolution.data_type ?? '').toUpperCase();
+    const operand = { text, resolved: true, canonical: resolution.canonical ?? text, data_type: type === '' ? undefined : type };
+    seen.push(operand);
+    if (kind === 'BOOL' && type !== 'BOOL') {
+        throw new L5xError('INVALID_OPERAND', `${text} is ${type || 'an unknown type'}; this slot needs a BOOL tag.`, 'Use a BOOL tag, or an alias that resolves to BOOL.', []);
+    }
+    if (kind === 'NUMBER' && !NUMERIC_TYPES.has(type)) {
+        throw new L5xError('INVALID_OPERAND', `${text} is ${type || 'an unknown type'}; this slot needs a numeric value or tag.`, 'Pass a numeric literal or an INT, DINT, REAL or similar tag.', []);
+    }
+    if (kind === 'TIMER' && !TIMER_TYPES.has(type)) {
+        throw new L5xError('INVALID_OPERAND', `${text} is ${type || 'an unknown type'}; this slot needs a timer.`, 'Pass a declared TIMER tag (TON, TOF or RTO instance).', []);
+    }
+    return operand;
+}
+/** Resolve one instruction node and emit it. */
+function composeInstruction(project, node, operands, counter) {
+    const args = node.args ?? [];
+    counter.instructions += 1;
+    if (counter.instructions > MAX_INSTRUCTIONS) {
+        throw new L5xError('LADDER_TOO_LARGE', `One rung may hold at most ${MAX_INSTRUCTIONS} instructions.`, 'Split the logic across rungs.');
+    }
+    const instruction = instructionByName(node.instr);
+    if (instruction !== undefined) {
+        const required = instruction.operands.filter(slot => slot.optional !== true).length;
+        if (args.length < required || args.length > instruction.operands.length) {
+            const shape = instruction.operands.map(slot => `${slot.name}${slot.optional === true ? '?' : ''}`).join(', ');
+            throw new L5xError('INVALID_OPERAND', `${instruction.name} takes ${required === instruction.operands.length ? String(required) : `${required}-${instruction.operands.length}`} operand(s): ${shape}; ${args.length} were supplied.`, `Call list_instructions with filter "${instruction.name}" for the exact operand order.`);
+        }
+        for (const [index, argument] of args.entries())
+            checkOperand(project, argument, instruction.operands[index].kind, operands);
+        return { text: `${instruction.name}(${args.join(',')})`, grounding: 'catalog' };
+    }
+    const aoi = project.document.aois.find(entry => entry.name.toUpperCase() === node.instr.toUpperCase());
+    if (aoi === undefined) {
+        throw new L5xError('UNKNOWN_INSTRUCTION', `"${node.instr}" is neither a catalogued instruction nor an AOI declared in this export.`, 'Call list_instructions for the catalog; an AOI must be declared in the project.', nearestInstructions(node.instr));
+    }
+    // AOI pins are declared by the AOI, not by this catalog; the operand text is
+    // still resolved so a typo in a tag cannot reach the draft.
+    for (const argument of args)
+        checkOperand(project, argument, 'ANY', operands);
+    return { text: `${aoi.name}(${args.join(',')})`, grounding: 'aoi' };
+}
+/** Emit one node tree, validating as it goes. */
+function composeNode(project, node, operands, counter, depth, grounds) {
+    if (depth > MAX_DEPTH)
+        throw new L5xError('LADDER_TOO_LARGE', `Branch nesting exceeds ${MAX_DEPTH}.`, 'Flatten the branches.');
+    if ('parallel' in node) {
+        if (!Array.isArray(node.parallel) || node.parallel.length < 2) {
+            throw new L5xError('INVALID_LADDER_SPEC', 'A parallel branch needs at least two paths.', 'Wrap the alternative paths in "parallel": [[...],[...]].');
+        }
+        const paths = node.parallel.map(path => {
+            if (!Array.isArray(path) || path.length === 0)
+                throw new L5xError('INVALID_LADDER_SPEC', 'A parallel path cannot be empty.', 'Give every path at least one instruction.');
+            return path.map(entry => composeNode(project, entry, operands, counter, depth + 1, grounds)).join('');
+        });
+        return `[${paths.join(' ,')} ]`;
+    }
+    if ('series' in node) {
+        if (!Array.isArray(node.series) || node.series.length === 0) {
+            throw new L5xError('INVALID_LADDER_SPEC', 'A series cannot be empty.', 'Give the series at least one instruction.');
+        }
+        return node.series.map(entry => composeNode(project, entry, operands, counter, depth + 1, grounds)).join('');
+    }
+    const composed = composeInstruction(project, node, operands, counter);
+    grounds.add(composed.grounding);
+    return composed.text;
+}
+/** Validate the rung we just emitted with the parser the draft path uses. */
+function verify(project, text, operands, instructions, grounds) {
+    const parsed = parseLadder(text);
+    if (parsed.issues.length > 0) {
+        // The composer produced text its own parser rejects: a defect, never a draft.
+        throw new L5xError('COMPOSER_DEFECT', `The composed rung does not parse: ${parsed.issues[0]?.message ?? 'unknown issue'}`, 'This is a plugin defect; report the spec that produced it.');
+    }
+    const grounding = grounds.size === 2 ? 'mixed' : grounds.has('aoi') ? 'aoi' : 'catalog';
+    return { neutral_text: text, instructions, operands, grounding };
+}
+/**
+ * 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 function composeRung(project, spec) {
+    const operands = [];
+    const counter = { instructions: 0 };
+    const grounds = new Set();
+    const text = `${composeNode(project, spec, operands, counter, 0, grounds)};`;
+    if (counter.instructions === 0)
+        throw new L5xError('INVALID_LADDER_SPEC', 'The specification contains no instruction.', 'Give the rung at least one instruction.');
+    return verify(project, text, operands, counter.instructions, grounds);
+}
+/** A required pattern argument. */
+function arg(args, name) {
+    const value = args[name];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new L5xError('INVALID_ARGUMENT', `Pattern argument ${name} must be a non-empty string.`, `Pass ${name} as a declared tag name.`);
+    }
+    return value.trim();
+}
+/** A pattern's named tags, expanded to one or two rungs. */
+export function composePattern(project, pattern, args) {
+    const one = (spec) => ({ rungs: [composeRung(project, spec)], pattern });
+    if (pattern === 'start_stop_latch') {
+        const start = arg(args, 'start');
+        const stop = arg(args, 'stop');
+        const run = arg(args, 'run');
+        return one({ series: [
+                { parallel: [[{ instr: 'XIC', args: [start] }], [{ instr: 'XIC', args: [run] }]] },
+                { instr: 'XIO', args: [stop] },
+                { instr: 'OTE', args: [run] },
+            ] });
+    }
+    if (pattern === 'interlock') {
+        const conditions = args.conditions;
+        if (!Array.isArray(conditions) || conditions.length === 0) {
+            throw new L5xError('INVALID_ARGUMENT', 'interlock needs conditions: at least one tag.', 'Pass conditions as an array of declared BOOL tag names.');
+        }
+        const output = arg(args, 'output');
+        return one({ series: [
+                ...conditions.map(condition => ({ instr: 'XIC', args: [String(condition)] })),
+                { instr: 'OTE', args: [output] },
+            ] });
+    }
+    if (pattern === 'ton_delay') {
+        const enable = arg(args, 'enable');
+        const timer = arg(args, 'timer');
+        const preset = args.preset_ms;
+        if (typeof preset !== 'number' || !Number.isFinite(preset) || preset < 0) {
+            throw new L5xError('INVALID_ARGUMENT', 'ton_delay needs preset_ms as a non-negative number.', 'Pass the preset in milliseconds, for example 1500.');
+        }
+        return one({ series: [{ instr: 'XIC', args: [enable] }, { instr: 'TON', args: [timer, String(preset)] }] });
+    }
+    // fault_latch: set on the fault, clear on the reset — two rungs, never one.
+    const fault = arg(args, 'fault');
+    const reset = arg(args, 'reset');
+    const latched = arg(args, 'latched');
+    return {
+        pattern,
+        rungs: [
+            composeRung(project, { series: [{ instr: 'XIC', args: [fault] }, { instr: 'OTL', args: [latched] }] }),
+            composeRung(project, { series: [{ instr: 'XIC', args: [reset] }, { instr: 'OTU', args: [latched] }] }),
+        ],
+    };
+}

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

@@ -31,6 +31,7 @@ export { ProjectSession } from './session.ts';
 export { readTools } from './tools/read.ts';
 export { referenceTools } from './tools/references.ts';
 export { checkTools } from './tools/checks.ts';
+export { documentTools } from './tools/document.ts';
 export { L5xError } from './core/errors.ts';
 export type { NextStep, Coverage, Success } from './core/result.ts';
 export type { ToolDefinition } from './core/tool.ts';

package/vendor/l5x/lib/index.js

@@ -12,6 +12,7 @@ import { ProjectSession } from "./session.js";
 import { readTools } from "./tools/read.js";
 import { referenceTools } from "./tools/references.js";
 import { checkTools } from "./tools/checks.js";
+import { documentTools } from "./tools/document.js";
 /** Plugin name in a composition. */
 export const name = 'l5x-read';
 /** Services this plugin cannot register without. */
@@ -31,7 +32,7 @@ export function apply(ctx, config = {}) {
     }
     const session = new ProjectSession(ctx.fs, maxFileBytes);
     ctx.provide?.(PROJECTS_SERVICE, session);
-    for (const definition of [...readTools(session), ...referenceTools(session), ...checkTools(session)]) {
+    for (const definition of [...readTools(session), ...referenceTools(session), ...checkTools(session), ...documentTools(session)]) {
         ctx.tools.register(definition);
     }
 }
@@ -39,4 +40,5 @@ export { ProjectSession } from "./session.js";
 export { readTools } from "./tools/read.js";
 export { referenceTools } from "./tools/references.js";
 export { checkTools } from "./tools/checks.js";
+export { documentTools } from "./tools/document.js";
 export { L5xError } from "./core/errors.js";

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

@@ -175,7 +175,12 @@ function decodeLines(routine) {
 function decodeRung(rung) {
     const textElement = firstChild(rung, 'Text');
     const text = textElement === undefined ? '' : (nodeText(textElement) ?? '').trim();
-    const comment = optionalAttribute(rung, 'Comment', '');
+    // Current exports write the comment as a <Comment> child (CDATA); older ones
+    // used the attribute. Reading only the attribute dropped 572 real comments in
+    // one project, which is what a documentation pass needs most.
+    const commentElement = firstChild(rung, 'Comment');
+    const fromChild = commentElement === undefined ? undefined : nodeText(commentElement);
+    const comment = (fromChild ?? optionalAttribute(rung, 'Comment', '')).trim();
     const number = Number.parseInt(attribute(rung, 'Number'), 10);
     if (comment === '')
         return { number, text };

package/vendor/l5x/lib/session.d.ts

@@ -101,6 +101,26 @@ export declare class ProjectSession {
      * @returns The resolved path.
      */
     resolvePath(requestedPath: string, exec?: ExecContext): Promise<string>;
+    /**
+     * Whether one path already exists.
+     *
+     * @param requestedPath - Path as the caller supplied it.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns True when the provider reports a file or folder there.
+     */
+    exists(requestedPath: string, exec?: ExecContext): Promise<boolean>;
+    /**
+     * Write one text file at an exact path, without the `.L5X` restriction.
+     *
+     * Used by the documentation bundle: the provider creates missing parent
+     * folders, so a new `output_root` needs no separate mkdir.
+     *
+     * @param requestedPath - Destination as the caller supplied it.
+     * @param text - File contents.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns The resolved destination.
+     */
+    writeTextAt(requestedPath: string, text: string, exec?: ExecContext): Promise<string>;
     /**
      * Write one prepared draft to a new path, never overwriting.
      *

package/vendor/l5x/lib/session.js

@@ -144,6 +144,42 @@ export class ProjectSession {
         });
         return target.displayPath;
     }
+    /**
+     * Whether one path already exists.
+     *
+     * @param requestedPath - Path as the caller supplied it.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns True when the provider reports a file or folder there.
+     */
+    async exists(requestedPath, exec) {
+        const target = await this.fs.resolve(requestedPath, {
+            ...(exec?.cwd === undefined ? {} : { cwd: exec.cwd }),
+            ...(exec?.signal === undefined ? {} : { signal: exec.signal }),
+        });
+        return (await this.fs.stat(target, exec?.signal)) !== undefined;
+    }
+    /**
+     * Write one text file at an exact path, without the `.L5X` restriction.
+     *
+     * Used by the documentation bundle: the provider creates missing parent
+     * folders, so a new `output_root` needs no separate mkdir.
+     *
+     * @param requestedPath - Destination as the caller supplied it.
+     * @param text - File contents.
+     * @param exec - Calling context: cancellation and workspace root.
+     * @returns The resolved destination.
+     */
+    async writeTextAt(requestedPath, text, exec) {
+        if (this.fs.writeText === undefined) {
+            throw new L5xError('OUTPUT_UNAVAILABLE', 'The filesystem provider in this profile cannot write files.', 'Use a profile whose filesystem provider allows writes.');
+        }
+        const target = await this.fs.resolve(requestedPath, {
+            ...(exec?.cwd === undefined ? {} : { cwd: exec.cwd }),
+            ...(exec?.signal === undefined ? {} : { signal: exec.signal }),
+        });
+        await this.fs.writeText(target, text, { kind: 'createIfAbsent' }, exec?.signal);
+        return target.displayPath;
+    }
     /**
      * Write one prepared draft to a new path, never overwriting.
      *

package/vendor/l5x/lib/tools/document.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The documentation and generation-reference tools.
+ *
+ * `list_instructions` is the catalog the composer validates against, exposed so a
+ * caller can read operand order instead of guessing it. `document_project` builds
+ * the handover bundle into a new folder: it writes documents, never the project.
+ *
+ * @module dsh-engineering-l5x/tools/document
+ */
+import type { ToolDefinition } from '../core/tool.ts';
+import type { ProjectSession } from '../session.ts';
+/**
+ * The documentation tools.
+ *
+ * @param session - Project handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export declare function documentTools(session: ProjectSession): readonly ToolDefinition[];