@aryacode/dsh-engineering 0.6.0 → 0.7.0

package/vendor/l5x/lib/tools/document.js

@@ -0,0 +1,119 @@
+/**
+ * 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 { DOCUMENT_PARTS, buildDocumentation } from "../engine/documentation.js";
+import { INSTRUCTIONS } from "../engine/instructions.js";
+import { L5xError } from "../core/errors.js";
+import { success } from "../core/result.js";
+import { choice, integer, list, object, string } from "../core/params.js";
+import { PROJECT_ID, optionalString, requiredString, tool } from "./common.js";
+/** What a catalog listing cannot establish. */
+const CATALOG_COVERAGE = {
+    complete: false,
+    unverified: [
+        'vendor instructions outside this catalog',
+        'operand coercion the controller applies at compile time',
+        'runtime behavior',
+    ],
+};
+/** What a generated document bundle cannot establish. */
+const DOCUMENT_COVERAGE = {
+    complete: false,
+    unverified: [
+        'narrative prose: the bundle carries structure, citations and existing descriptions only',
+        'cause-and-effect and FAT/SAT documents are not generated',
+        'runtime behavior and anything outside the export (HMI, produced/consumed tags, drivers)',
+    ],
+};
+/** One catalog row as the tool returns it. */
+function catalogRow(instruction) {
+    return {
+        name: instruction.name,
+        category: instruction.category,
+        summary: instruction.summary,
+        operands: instruction.operands.map(slot => ({ name: slot.name, kind: slot.kind, required: slot.optional !== true })),
+    };
+}
+/**
+ * The documentation tools.
+ *
+ * @param session - Project handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export function documentTools(session) {
+    return [
+        tool({
+            name: 'list_instructions',
+            description: 'List the ladder instructions the composer validates: mnemonic, category, summary and operand slots with their kinds. Read it before composing a rung instead of guessing operand order.',
+            parameters: object({
+                filter: string('Case-insensitive substring matched against the instruction name, category or summary.'),
+                category: string('Only instructions in this category, for example "Comparison".'),
+                limit: integer('Maximum rows to return.', { minimum: 1, maximum: 200, default: 100 }),
+            }, []),
+            async run(args) {
+                const filter = (optionalString(args, 'filter') ?? '').toLowerCase();
+                const category = (optionalString(args, 'category') ?? '').toLowerCase();
+                const limit = typeof args.limit === 'number' ? Math.min(Math.max(Math.trunc(args.limit), 1), 200) : 100;
+                const rows = INSTRUCTIONS
+                    .filter(instruction => category === '' || instruction.category.toLowerCase() === category)
+                    .filter(instruction => filter === '' || instruction.name.toLowerCase().includes(filter)
+                    || instruction.category.toLowerCase().includes(filter)
+                    || instruction.summary.toLowerCase().includes(filter));
+                return success(`${rows.length} instruction(s)${category === '' ? '' : ` in ${category}`}${filter === '' ? '' : ` matching ${JSON.stringify(filter)}`}; showing ${Math.min(rows.length, limit)}.`, {
+                    total: rows.length,
+                    categories: [...new Set(INSTRUCTIONS.map(instruction => instruction.category))],
+                    rows: rows.slice(0, limit).map(catalogRow),
+                }, [{ tool: 'compose_rung', why: 'Compose a rung from the instruction and its operand order.' }], CATALOG_COVERAGE);
+            },
+        }),
+        tool({
+            name: 'document_project',
+            description: 'Write a documentation bundle for the open project into a NEW folder: project summary, I/O list, tag CSVs (including the Studio Tags and Comments shape) and per-program rung documentation with comments and referenced tags. Never writes to the export.',
+            parameters: object({
+                output_root: string('New folder for the bundle. It must not exist. Example: "C:/Projects/Line/documentation".'),
+                include: list('Optional parts to produce; default all. One of project, io, tags, rungs.', choice('One part.', DOCUMENT_PARTS)),
+                programs: list('Optional program names to restrict the bundle to.', string('Program name.')),
+                routines: list('Optional routine names to restrict the rung documentation to.', string('Routine name.')),
+                rungs_per_file: integer('Most rungs per rung-documentation file before a continuation file is written. Defaults to 200.', { minimum: 1, maximum: 2000 }),
+                project_id: PROJECT_ID,
+            }, ['output_root']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const outputRoot = requiredString(args, 'output_root');
+                const include = Array.isArray(args.include) && args.include.length > 0
+                    ? args.include.map(String)
+                    : undefined;
+                const unknown = include?.filter(part => !DOCUMENT_PARTS.includes(part));
+                if (unknown !== undefined && unknown.length > 0) {
+                    throw new L5xError('INVALID_ARGUMENT', `Unknown part(s): ${unknown.join(', ')}.`, `Pass any of: ${DOCUMENT_PARTS.join(', ')}.`);
+                }
+                if (await session.exists(outputRoot, exec)) {
+                    throw new L5xError('OUTPUT_EXISTS', `A file or folder already exists at ${outputRoot}.`, 'Pass a new output_root; the generator never merges into an existing folder.');
+                }
+                const bundle = buildDocumentation(project, {
+                    ...(include === undefined ? {} : { include }),
+                    ...(Array.isArray(args.programs) ? { programs: args.programs.map(String) } : {}),
+                    ...(Array.isArray(args.routines) ? { routines: args.routines.map(String) } : {}),
+                    ...(typeof args.rungs_per_file === 'number' ? { rungsPerFile: args.rungs_per_file } : {}),
+                });
+                const written = [];
+                for (const [path, text] of bundle.files) {
+                    const destination = await session.writeTextAt(`${outputRoot.replace(/[\\/]+$/u, '')}/${path}`, text, exec);
+                    written.push({ path: destination, bytes: new TextEncoder().encode(text).length });
+                }
+                return success(`Wrote ${written.length} file(s) for ${bundle.counts.programs} program(s), ${bundle.counts.routines} routine(s), ${bundle.counts.rungs} rung(s) (${bundle.counts.comments} commented) to ${outputRoot}.`, {
+                    output_root: outputRoot,
+                    files: written,
+                    counts: bundle.counts,
+                    excluded: bundle.excluded,
+                }, [{ tool: 'draft_rung_comment', why: 'Write the approved narrative back as rung comments, then apply the draft.' }], DOCUMENT_COVERAGE);
+            },
+        }),
+    ];
+}

package/vendor/l5x/lib/tools/drafts.js

@@ -9,6 +9,7 @@
  * @module dsh-engineering-l5x/tools/drafts
  */
 import { prepareChangeSet } from "../engine/change-set.js";
+import { composePattern, composeRung, PATTERNS } from "../engine/ladder.js";
 import { L5xError } from "../core/errors.js";
 import { success } from "../core/result.js";
 import { choice, integer, object, string } from "../core/params.js";
@@ -26,6 +27,30 @@ const DRAFT_COVERAGE = {
 function requestOf(draft) {
     return JSON.stringify({ version: 1, operations: draft.operations });
 }
+/** What a composed rung does not prove. */
+const COMPOSED_COVERAGE = {
+    complete: false,
+    unverified: [
+        'compiled behaviour: the composer validates instruction names, operand counts and operand types only',
+        'Studio 5000 import and build are not performed by this surface',
+        'runtime behavior',
+    ],
+};
+/** Parse one JSON-object argument, refusing anything else. */
+function jsonObject(value, name) {
+    if (value === undefined)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw invalid(name, `${name} is not valid JSON.`, `Pass a JSON object, for example {"start":"Start"}.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw invalid(name, `${name} must be a JSON object.`, 'Pass a JSON object.');
+    return parsed;
+}
 /** The success document every append answers with. */
 function appended(draft, operation) {
     return success(`Draft ${draft.id}: ${draft.operations.length} ${draft.operations.length === 1 ? 'operation' : 'operations'}.`, { draft_id: draft.id, operation_count: draft.operations.length, last_operation: operation }, [{ tool: 'draft_validate', args: { draft_id: draft.id }, why: 'Validate the whole draft before writing anything.' }]);
@@ -43,7 +68,7 @@ export function draftTools(session, drafts, maxOperations, maxFileBytes) {
     return [
         tool({
             name: 'draft_rung',
-            description: 'Append one ladder rung operation to the chat draft: replace, insert or delete. Nothing is written until draft_apply.',
+            description: 'Append one ladder rung operation to the chat draft: replace, insert or delete. Optionally carries the rung comment. Nothing is written until draft_apply.',
             parameters: object({
                 program: string('Program that owns the routine. Example: "MainProgram".'),
                 routine: string('Routine the rung belongs to. Example: "MainRoutine".'),
@@ -51,6 +76,7 @@ export function draftTools(session, drafts, maxOperations, maxFileBytes) {
                 rung: integer('Rung number the operation targets. Required for replace and delete; for insert it is the new rung number.', { minimum: 0 }),
                 text: string('NeutralText for replace or insert. Omit for delete. Example: "XIC(Start)OTE(Run);"'),
                 before_rung: integer('For insert only: insert before this rung number instead of after rung.', { minimum: 0 }),
+                comment: string('Optional rung comment, written above the rung in Studio. Omit to leave an existing comment unchanged.'),
                 project_id: PROJECT_ID,
             }, ['program', 'routine', 'mode']),
             async run(args, exec) {
@@ -61,6 +87,7 @@ export function draftTools(session, drafts, maxOperations, maxFileBytes) {
                 const text = optionalString(args, 'text');
                 const rung = optionalInteger(args, 'rung');
                 const before = optionalInteger(args, 'before_rung');
+                const comment = args.comment === undefined ? undefined : String(args.comment);
                 let operation;
                 if (mode === 'delete') {
                     if (rung === undefined)
@@ -70,12 +97,12 @@ export function draftTools(session, drafts, maxOperations, maxFileBytes) {
                 else if (mode === 'replace') {
                     if (rung === undefined || text === undefined)
                         throw invalid('rung and text', 'Required when mode is replace.', 'Pass the rung number and its new NeutralText.');
-                    operation = { operation: 'replace_rung', program, routine, rung, text };
+                    operation = { operation: 'replace_rung', program, routine, rung, text, ...(comment === undefined ? {} : { comment }) };
                 }
                 else if (mode === 'insert') {
                     if (rung === undefined || text === undefined)
                         throw invalid('rung and text', 'Required when mode is insert.', 'Pass the new rung number and its NeutralText.');
-                    operation = { operation: 'insert_rung', program, routine, rung, text, ...(before === undefined ? {} : { before_rung: before }) };
+                    operation = { operation: 'insert_rung', program, routine, rung, text, ...(before === undefined ? {} : { before_rung: before }), ...(comment === undefined ? {} : { comment }) };
                 }
                 else {
                     throw invalid('mode', `Unknown mode ${JSON.stringify(mode)}.`, 'Pass one of: replace, insert, delete.');
@@ -83,6 +110,85 @@ export function draftTools(session, drafts, maxOperations, maxFileBytes) {
                 return appended(drafts.append(exec, project.id, operation, maxOperations), operation);
             },
         }),
+        tool({
+            name: 'draft_rung_comment',
+            description: 'Append one rung-comment change to the chat draft. Sets or clears the comment Studio shows above a rung; the logic is untouched. Nothing is written until draft_apply.',
+            parameters: object({
+                program: string('Program that owns the routine. Example: "MainProgram".'),
+                routine: string('Ladder routine the rung belongs to. Example: "MainRoutine".'),
+                rung: integer('Rung number whose comment changes.', { minimum: 0 }),
+                comment: string('New comment text. Pass an empty string to clear an existing comment.'),
+                project_id: PROJECT_ID,
+            }, ['program', 'routine', 'rung', 'comment']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const operation = {
+                    operation: 'set_rung_comment',
+                    program: requiredString(args, 'program'),
+                    routine: requiredString(args, 'routine'),
+                    rung: optionalInteger(args, 'rung') ?? 0,
+                    comment: typeof args.comment === 'string' ? args.comment : '',
+                };
+                return appended(drafts.append(exec, project.id, operation, maxOperations), operation);
+            },
+        }),
+        tool({
+            name: 'compose_rung',
+            description: 'Compose one validated ladder rung from a structure or a named pattern, checking every instruction and operand against the export, and optionally stage it in the draft. Never emits text that fails the ladder parser.',
+            parameters: object({
+                pattern: choice('Named pattern to expand. fault_latch produces two rungs.', PATTERNS),
+                spec_json: string('Composition tree as JSON, for example {"series":[{"instr":"XIC","args":["Start"]},{"instr":"OTE","args":["Run"]}]}.'),
+                arguments_json: string('Pattern arguments as JSON, for example {"start":"Start","stop":"Stop","run":"Run"}.'),
+                program: string('Program to stage into. Omit to return the composed text only.'),
+                routine: string('Routine to stage into. Required with program.'),
+                mode: choice('insert adds a rung; replace rewrites one.', ['insert', 'replace']),
+                rung: integer('Rung number for a staged operation. For a two-rung pattern, the second uses rung + 1.', { minimum: 0 }),
+                before_rung: integer('For insert: insert before this rung number instead of after rung.', { minimum: 0 }),
+                comment: string('Optional rung comment for the staged rung.'),
+                draft_id: string('Draft handle to append to. Omit when exactly one draft exists in this chat.'),
+                project_id: PROJECT_ID,
+            }, []),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const pattern = optionalString(args, 'pattern');
+                const specJson = optionalString(args, 'spec_json');
+                if ((pattern === undefined) === (specJson === undefined)) {
+                    throw invalid('pattern or spec_json', 'Pass exactly one of a named pattern or a composition tree.', 'Use pattern + arguments_json for a common shape, or spec_json for explicit logic.');
+                }
+                let composed;
+                if (pattern !== undefined) {
+                    if (!PATTERNS.includes(pattern))
+                        throw invalid('pattern', `Unknown pattern ${JSON.stringify(pattern)}.`, `Pass one of: ${PATTERNS.join(', ')}.`);
+                    composed = composePattern(project, pattern, jsonObject(typeof args.arguments_json === 'string' ? args.arguments_json : undefined, 'arguments_json'));
+                }
+                else {
+                    const spec = jsonObject(specJson, 'spec_json');
+                    composed = { rungs: [composeRung(project, spec)] };
+                }
+                const program = optionalString(args, 'program');
+                const routine = optionalString(args, 'routine');
+                const mode = optionalString(args, 'mode');
+                const rung = optionalInteger(args, 'rung');
+                const staged = program !== undefined || routine !== undefined || mode !== undefined || rung !== undefined;
+                if (!staged) {
+                    return success(`Composed ${composed.rungs.length} rung(s)${composed.pattern === undefined ? '' : ` from ${composed.pattern}`}; pass program and routine to stage it.`, { pattern: composed.pattern, rungs: composed.rungs }, [{ tool: 'compose_rung', args: { spec_json: '{"series":[]}' }, why: 'Adjust the structure, or stage this text with draft_rung.' }], COMPOSED_COVERAGE);
+                }
+                if (program === undefined || routine === undefined || mode === undefined || rung === undefined) {
+                    throw invalid('program, routine, mode and rung', 'Staging needs all four.', 'Pass program, routine, mode and rung together, or none of them.');
+                }
+                if (composed.rungs.length > 1 && mode === 'replace')
+                    throw invalid('mode', 'A two-rung pattern cannot replace one rung.', 'Use mode insert, or compose a single rung.');
+                let draft;
+                for (const [index, composedRung] of composed.rungs.entries()) {
+                    const operation = mode === 'replace'
+                        ? { operation: 'replace_rung', program, routine, rung, text: composedRung.neutral_text, ...(typeof args.comment === 'string' ? { comment: args.comment } : {}) }
+                        : { operation: 'insert_rung', program, routine, rung: rung + index, text: composedRung.neutral_text, ...(index === 0 && args.before_rung !== undefined ? { before_rung: optionalInteger(args, 'before_rung') } : {}), ...(typeof args.comment === 'string' ? { comment: args.comment } : {}) };
+                    draft = drafts.append(exec, project.id, operation, maxOperations);
+                }
+                const stagedDraft = draft;
+                return success(`Composed and staged ${composed.rungs.length} rung(s)${composed.pattern === undefined ? '' : ` from ${composed.pattern}`}. Draft ${stagedDraft.id}: ${stagedDraft.operations.length} operation(s).`, { draft_id: stagedDraft.id, operation_count: stagedDraft.operations.length, pattern: composed.pattern, rungs: composed.rungs }, [{ tool: 'draft_validate', args: { draft_id: stagedDraft.id }, why: 'Validate the whole draft before writing anything.' }], COMPOSED_COVERAGE);
+            },
+        }),
         tool({
             name: 'draft_st',
             description: 'Append one Structured Text body replacement to the chat draft. Nothing is written until draft_apply.',