@aryacode/dsh-engineering 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.7.0] - 2026-10-27
+
+### Added
+
+- **Ladder generation that cannot emit invalid NeutralText.** Three pieces:
+  - `list_instructions` — the instruction catalog the composer validates: mnemonic, category, summary
+    and operand slots with their kinds (BOOL, NUMBER, TIMER, …), filterable. 41 instructions, covering
+    every mnemonic the Laminator project uses (45 distinct across 860 rungs).
+  - `compose_rung` — builds one rung from a structure tree (`spec_json`) or a named pattern
+    (`start_stop_latch`, `fault_latch`, `ton_delay`, `interlock`), resolves every operand against the
+    export (including unqualified program tags and aliases), type-checks each slot, emits the export's
+    own bracket style, and re-parses its output with the same parser `draft_rung` uses. Unknown
+    instructions name the nearest catalog entries; a wrong operand count, a non-BOOL contact, a
+    non-numeric value slot, an undeclared tag or an undeclared AOI is refused before anything is staged.
+    Passing `program`, `routine`, `mode` and `rung` stages the rung in the draft; `fault_latch` stages
+    its two rungs consecutively.
+- **Rung comments are read and written.** The model read the `Comment` **attribute** only, so a real
+  Studio export's 572 child `<Comment>` elements were invisible. `decodeRung` now supports both shapes,
+  `draft_rung` accepts a `comment`, and `draft_rung_comment` sets or clears one on an existing rung.
+  CDATA terminators in a comment round-trip through the existing escaping.
+- **Documentation dimension.** `document_project` writes a handover bundle into a NEW folder and never
+  touches the export: `PROJECT.md` (controller, revision, tasks, programs, counts), `io.md`/`io.csv`,
+  `tags.csv` and `tags-studio.csv` (the `Tag Name,Description` shape Studio's Tags and Comments import
+  expects), and `rungs/<program>.md` with each rung's number, comment, NeutralText, instructions and
+  resolved tags. Filters: `include`, `programs`, `routines`, `rungs_per_file`.
+
+### Documentation
+
+- `packages/l5x/SKILL.md`: a Generate section (catalog → compose → validate → apply) and a
+  Documentation section (bundle contents, the comment round trip, what the bundle cannot prove).
+- README: 89 tools, L5X 44, and the 0.7.0 milestone.
+
 ## [0.6.0] - 2026-10-27
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 MotionWorks IEC and FactoryTalk Optix sit behind a single install, one row per surface. A row is the
 switch: disable it and that plugin unloads, so its tool schemas leave the request.
 
-`@aryacode/dsh-engineering` · 85 tools · 5 rows · 4 products · MIT
+`@aryacode/dsh-engineering` · 89 tools · 5 rows · 4 products · MIT
 
 ---
 
@@ -36,14 +36,14 @@ bundle.
 
 | Product | Tools | Default | Needs |
 |---|---|---|---|
-| **Studio 5000 L5X** | 40 | all on | Node for offline reads; Studio 5000 + Logix Designer SDK for SDK work; a controller for live |
+| **Studio 5000 L5X** | 44 | all on | Node for offline reads; Studio 5000 + Logix Designer SDK for SDK work; a controller for live |
 | **FactoryTalk View ME** | 14 | all on | Node for an export folder; FactoryTalk View Studio ME for discovery and the handoff |
 | **MotionWorks IEC** | 24 | all on | MotionWorks IEC 3 Pro installed; verified against 1.19 |
 | **FactoryTalk Optix** | 10 (3 need preview) | all on | Optix Studio installed; Tesseract for OCR |
 
 Tool groups, by product:
 
-- **L5X** — 11 read (`open_project` … `compare_projects`), 9 staged drafts (`draft_*`), 6 Logix
+- **L5X** — 13 read (`open_project` … `document_project`), 11 staged drafts (`draft_*`, `compose_rung`), 6 Logix
   Designer SDK, 7 supervised controller, 7 live EtherNet/IP (2 reads, 2 identity/discovery, 1 batch read, 2 approval-gated writes)
 - **FactoryTalk View** — 6 read, 5 staged edits, 3 Studio handoff
 - **MotionWorks IEC** — 7 session, 7 saved-project reads, 3 verify, 7 direct edits
@@ -120,6 +120,7 @@ the lean profile is the one that turns them off.
 
 | Version | What landed |
 |---|---|
+| **0.7.0** | Ladder generation that cannot emit invalid NeutralText: an instruction catalog, a pattern/tree composer that resolves and type-checks every operand, rung comments read and written, and a documentation bundle (`document_project`) with the Studio tags-and-comments CSV |
 | **0.5.0** | Commissioned on real files: FactoryTalk View reads genuine Studio exports (`<gfx>` displays, comma CSVs, UTF-16) instead of reporting zero; L5X alias resolution cuts 315 false "unresolved reference" findings to 16 on a 1279-tag project; `add_tag` no longer demands a value; a locked ACD exports from a copy |
 | **0.4.17** | MotionWorks edits the real project again: the pre-edit backup is written where the bridge and engine verify it, an already-open project is attached instead of reloaded, and `mw_get` returns the body hash the edit takes |
 | **0.4.15** | Every tool surface ships on by default; the row Configure pages switch them off |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryacode/dsh-engineering",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "AryaCode engineering bundle: one install surface for the Studio 5000 L5X, FactoryTalk View ME, MotionWorks IEC and FactoryTalk Optix surfaces, one row per product, with the ladder and display previews.",
   "keywords": [
     "dsh",
@@ -55,15 +55,6 @@
       ]
     }
   },
-  "scripts": {
-    "test": "node --import tsx --test test/patch.spec.mjs test/docs.spec.mjs test/tool-reference.spec.mjs test/manifests.spec.mjs test/client-face.spec.mjs test/config.spec.mjs test/netlogic.spec.mjs",
-    "docs:tools": "tsx scripts/gen-tool-reference.ts",
-    "docs:check": "tsx scripts/gen-tool-reference.ts --check",
-    "netlogic:sync": "node scripts/sync-netlogic.mjs",
-    "build:client": "node scripts/build-client.mjs",
-    "assemble": "node scripts/assemble.mjs",
-    "prepack": "node scripts/build-client.mjs && node scripts/assemble.mjs"
-  },
   "dependencies": {
     "fast-xml-parser": "5.11.1",
     "fast-xml-validator": "1.4.2",
@@ -103,5 +94,13 @@
     "./mwi/skill": "./vendor/mwi/lib/skill.js",
     "./mwi/verify": "./vendor/mwi/lib/verify.js",
     "./mwi/edit": "./vendor/mwi/lib/edit.js"
+  },
+  "scripts": {
+    "test": "node --import tsx --test test/patch.spec.mjs test/docs.spec.mjs test/tool-reference.spec.mjs test/manifests.spec.mjs test/client-face.spec.mjs test/config.spec.mjs test/netlogic.spec.mjs",
+    "docs:tools": "tsx scripts/gen-tool-reference.ts",
+    "docs:check": "tsx scripts/gen-tool-reference.ts --check",
+    "netlogic:sync": "node scripts/sync-netlogic.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "assemble": "node scripts/assemble.mjs"
   }
-}
+}

package/vendor/l5x/SKILL.md

@@ -56,12 +56,12 @@ this is a backup on request ("back up this project"). Build it as a copy plus
 
 ## Live reads
 
-The `l5x-live` entry reads declared scalar tags straight from a controller over EtherNet/IP, without Studio 5000, FactoryTalk Linx or the SDK. It may be disabled; if `poll_live_tags` is unavailable, say live reads are not enabled rather than trying another tool.
+`l5x-live` reads declared scalar tags over EtherNet/IP with no Studio, FactoryTalk Linx or SDK. If `poll_live_tags` is unavailable, say live reads are not enabled here.
 
-- `poll_live_tags` takes an explicit IPv4 address, a CPU slot and 1 to 16 declared scalar tags (`BOOL`, `INT`, `DINT`, `REAL`), and returns timestamped sweeps, quality and the controller identity.
+- `poll_live_tags` takes an explicit IPv4 address, a CPU slot and 1 to 16 declared scalars, and returns timestamped sweeps, quality and controller identity.
 - `start_plc_trend` samples the same way as a session-owned job the chart can follow; stop it through the job controls.
 - These are read-only. Never write controller data, force tags, toggle bits or edit online.
-- Report `live_logic_matches_export: "unverified"`: the read proves a value at a moment, not that the controller runs the exported logic, and sequential reads can miss transitions.
+- Report `live_logic_matches_export: "unverified"`: a read proves a value at a moment, not that the controller runs the export.
 
 ## Reporting
 
@@ -81,18 +81,38 @@ The `l5x-live` entry reads declared scalar tags straight from a controller over
 The `l5x-studio` entry adds offline SDK work; it may be disabled. Call `studio_sdk_status` before using it.
 
 - `export_acd_to_l5x` writes one new full L5X from an ACD. No controller contact.
-- `verify_offline_l5x` imports a full L5X into a new offline ACD and builds it. Build needs project revision 37 or later; `probe: true` attempts a lower revision and reports the SDK error. A Studio-exported L5X builds; an L5X produced by `export_acd_to_l5x` may be refused by the SDK as "no changes".
-- `build_acd_from_draft` imports one changed RLL or ST routine into a new ACD copy, builds it and exports it. The baseline must be an L5X exported from that ACD in this chat, and neither file may change afterwards.
+- `verify_offline_l5x` imports a full L5X into a new offline ACD and builds it. Build needs project revision 37+; `probe: true` tries a lower one and reports the SDK error. An L5X from `export_acd_to_l5x` may be refused as "no changes".
+- `build_acd_from_draft` imports one changed RLL or ST routine into a new ACD copy, builds and exports it. The baseline must be an L5X exported from that ACD in this chat; neither file may change.
 - `studio_review_evidence` checks program, routine and rung or line names and verbatim quotes before you report findings.
-- `controller_approval_status` reports whether this session can ask a human. `capture_controller_snapshot`, `change_controller_mode` and `download_project` each require per-call human approval of the exact controller, route and target, and proceed only on `allowed-once`; `download_project` accepts only a `verification_id` from a passed build in this chat.
+- `controller_approval_status` says whether this session can ask a human. `capture_controller_snapshot`, `change_controller_mode` and `download_project` need per-call approval of the exact target and proceed only on `allowed-once`; `download_project` takes a `verification_id` from a passed build in this chat.
 - `go_online`, `read_controller_mode` and `read_live_tag` are read-only and need no approval. Never write controller data, force tags, toggle bits or edit online.
 
 ## Editing
 
 Editing uses the `draft_*` family. It may be disabled in this profile; if a draft tool is unavailable, say editing is not enabled here rather than trying another tool.
 
-- One operation per call: `draft_rung`, `draft_st`, `draft_routine`, `draft_tag`, `draft_tag_description`, `draft_udt_member`, `draft_udt_description`. Each returns the draft id and the operation count.
+- One operation per call: `draft_rung`, `draft_rung_comment`, `draft_st`, `draft_routine`, `draft_tag`, `draft_tag_description`, `draft_udt_member`, `draft_udt_description`.
 - `draft_validate` prepares the accumulated draft against the project and returns its hash, diff summary and check findings. Read the findings before applying.
 - `draft_apply` writes the draft to ONE new `.L5X` path. It never overwrites an existing file.
 - After applying, reopen the written file with `open_project` to review it.
 - Drafts belong to this chat. Another chat starts with none, and an applied draft is cleared.
+
+## Generate
+
+Write ladder through the composer, not by inventing NeutralText.
+
+- `list_instructions` gives the mnemonic, category and operand slots with their kinds; read it before composing.
+- `compose_rung` builds one rung from a tree (`spec_json`) or a pattern (`start_stop_latch`, `fault_latch`, `ton_delay`, `interlock`), resolves every operand, type-checks each slot and parses its own output; anything unknown or mistyped is refused before staging.
+- Pass `program`, `routine`, `mode` and `rung` to stage it (plus `comment`); without them it returns text only.
+- `fault_latch` stages two rungs at `rung` and `rung + 1`; rung numbers are not renumbered, so pick free ones.
+
+## Documentation
+
+`document_project` writes a handover bundle into a NEW folder and never touches the export:
+
+- `PROJECT.md` — controller, revision, tasks, programs, counts;
+- `io.md` / `io.csv` — modules and module-data tags;
+- `tags.csv` and `tags-studio.csv` — every declared tag, and the `Tag Name,Description` shape Studio imports;
+- `rungs/<program>.md` — each rung's number, comment, NeutralText, instructions and resolved tags.
+
+The bundle is structure and citations, not prose: write the narrative yourself and use `draft_rung_comment` / `draft_tag_description` when it belongs in the project. No C&E, FAT/SAT or runtime proof.

package/vendor/l5x/lib/engine/change-set.d.ts

@@ -5,6 +5,7 @@ type Operation = {
     readonly routine: string;
     readonly rung: number;
     readonly text: string;
+    readonly comment?: string;
 } | {
     readonly operation: 'delete_rung';
     readonly program: string;
@@ -17,6 +18,13 @@ type Operation = {
     readonly rung: number;
     readonly text: string;
     readonly before_rung?: number;
+    readonly comment?: string;
+} | {
+    readonly operation: 'set_rung_comment';
+    readonly program: string;
+    readonly routine: string;
+    readonly rung: number;
+    readonly comment: string;
 } | {
     readonly operation: 'replace_st';
     readonly program: string;
@@ -59,7 +67,7 @@ type Operation = {
     readonly description: string;
 };
 /** Compact contract returned with validation errors and embedded in tool descriptions. */
-export declare const CHANGE_SET_HELP = "Operations (each also needs \"operation\"):\nreplace_rung {program,routine,rung,text}\ninsert_rung {program,routine,rung,text,before_rung?}\ndelete_rung {program,routine,rung}\nreplace_st {program,routine,code}\nadd_routine {program,name,language:\"RLL\"|\"ST\",code}\nadd_tag {scope,name,data_type,description,value? scalar, dimensions? \"4 2\", external_access? \"Read/Write\"|\"Read Only\"|\"None\"}\nset_tag_description {scope,name,description}\nadd_udt_member {udt,name,data_type,description}\nset_udt_description {udt,description}\nset_udt_member_description {udt,member,description}\nIdentifiers are at most 40 characters. Example: {\"version\":1,\"operations\":[{\"operation\":\"add_tag\",\"scope\":\"controller\",\"name\":\"SP_Start\",\"data_type\":\"REAL\",\"value\":80,\"description\":\"Start threshold\"}]}";
+export declare const CHANGE_SET_HELP = "Operations (each also needs \"operation\"):\nreplace_rung {program,routine,rung,text,comment?}\ninsert_rung {program,routine,rung,text,before_rung?,comment?}\ndelete_rung {program,routine,rung}\nset_rung_comment {program,routine,rung,comment}\nreplace_st {program,routine,code}\nadd_routine {program,name,language:\"RLL\"|\"ST\",code}\nadd_tag {scope,name,data_type,description,value? scalar, dimensions? \"4 2\", external_access? \"Read/Write\"|\"Read Only\"|\"None\"}\nset_tag_description {scope,name,description}\nadd_udt_member {udt,name,data_type,description}\nset_udt_description {udt,description}\nset_udt_member_description {udt,member,description}\nIdentifiers are at most 40 characters. Example: {\"version\":1,\"operations\":[{\"operation\":\"add_tag\",\"scope\":\"controller\",\"name\":\"SP_Start\",\"data_type\":\"REAL\",\"value\":80,\"description\":\"Start threshold\"}]}";
 /** Limits are resolved by the plugin's configuration before tools call this module. */
 export interface ChangeSetLimits {
     readonly operations: number;

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[];