@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

package/vendor/l5x/lib/editing.js

@@ -0,0 +1,42 @@
+/**
+ * The L5X editing entry: drafts over the read entry's project handles.
+ *
+ * Kept separate so a profile that only reads, checks and compares does not pay
+ * for nine draft schemas. It consumes the `l5xProjects` service the read entry
+ * provides, so a project is opened once and both entries see the same handle.
+ *
+ * @module dsh-engineering-l5x/editing
+ */
+import { DraftStore } from "./drafts.js";
+import { draftTools } from "./tools/drafts.js";
+import { PROJECTS_SERVICE } from "./index.js";
+/** Plugin name in a composition. */
+export const name = 'l5x-editing';
+/** The read entry's project service must already be mounted. */
+export const inject = ['tools', PROJECTS_SERVICE];
+/**
+ * Register the draft tools.
+ *
+ * @param ctx - Plugin context carrying the read entry's project service.
+ * @param config - Deployment limits.
+ */
+export function apply(ctx, config = {}) {
+    const session = ctx.get?.(PROJECTS_SERVICE);
+    if (session === undefined) {
+        throw new Error('l5x-editing: the l5xProjects service is unavailable; mount the L5X read entry before this one');
+    }
+    const maxFileBytes = config.maxFileBytes ?? 64 * 1024 * 1024;
+    if (!Number.isInteger(maxFileBytes) || maxFileBytes <= 0) {
+        throw new Error('l5x-editing: maxFileBytes must be a positive integer');
+    }
+    const maxDraftOperations = config.maxDraftOperations ?? 200;
+    if (!Number.isInteger(maxDraftOperations) || maxDraftOperations <= 0) {
+        throw new Error('l5x-editing: maxDraftOperations must be a positive integer');
+    }
+    const drafts = new DraftStore();
+    for (const definition of draftTools(session, drafts, maxDraftOperations, maxFileBytes)) {
+        ctx.tools.register(definition);
+    }
+}
+export { DraftStore } from "./drafts.js";
+export { draftTools } from "./tools/drafts.js";

package/vendor/l5x/lib/engine/acd-edit.d.ts

@@ -0,0 +1,13 @@
+import { type ProjectSnapshot } from '../session.ts';
+export declare function controllerContent(project: ProjectSnapshot, ignoreModifiedDate?: boolean, ignoreEncodedPayload?: boolean): string;
+/** Validate one edited routine component for review in the user's IDE.
+ * @param baseline - original routine export from Studio.
+ * @param draft - unchanged-on-disk proposal derived from that export.
+ * @param program - intended containing program.
+ * @param routine - intended existing routine.
+ * @returns import target and source identity; no Studio import or controller operation occurs.
+ */
+export declare function studioRoutineImportPlan(baseline: ProjectSnapshot, draft: ProjectSnapshot, program: string, routine: string): object;
+export declare function routineEditPlan(baseline: ProjectSnapshot, draft: ProjectSnapshot, program: string, routine: string): {
+    xpath: string;
+};

package/vendor/l5x/lib/engine/acd-edit.js

@@ -0,0 +1,115 @@
+import { documentRoot, elementChildren, firstChild, parseXml } from "../model/xml.js";
+import { EngineeringError } from "../session.js";
+import { reviewDownloadSource } from "./download-review.js";
+function controller(project) {
+    const node = firstChild(documentRoot(parseXml(project.xml)), 'Controller');
+    if (project.exportKind !== 'controller' || node === undefined)
+        throw new EngineeringError('CONTROLLER_EXPORT_REQUIRED', 'A full controller export is required');
+    return node;
+}
+function named(parent, kind, name) {
+    const matches = parent === undefined ? [] : elementChildren(parent, kind).filter(node => node.attrs.Name === name);
+    if (matches.length !== 1)
+        throw new EngineeringError('AMBIGUOUS_TARGET', `Expected one ${kind} named ${name}`);
+    return matches[0];
+}
+/** Compare every controller XML structure, including fields not modeled by the index. */
+function canonical(node, omit, ignoreModifiedDate = false, ignoreEncodedPayload = false) {
+    if (node === omit)
+        return '#target-routine';
+    if (!('children' in node))
+        return node.name === '#comment' || node.text.trim() === '' ? null : ['text', node.text];
+    const attrs = Object.entries(node.attrs).filter(([key]) => !(ignoreModifiedDate && node.name === 'Controller' && key === 'LastModifiedDate'));
+    const children = node.children.filter(child => !(ignoreEncodedPayload && node.name === 'EncodedData' && !('children' in child)));
+    return [node.name, attrs.sort(([a], [b]) => a.localeCompare(b)), children.map(child => canonical(child, omit, ignoreModifiedDate, ignoreEncodedPayload)).filter(value => value !== null)];
+}
+export function controllerContent(project, ignoreModifiedDate = false, ignoreEncodedPayload = false) {
+    return JSON.stringify(canonical(controller(project), undefined, ignoreModifiedDate, ignoreEncodedPayload));
+}
+/** Validate one edited routine component for review in the user's IDE.
+ * @param baseline - original routine export from Studio.
+ * @param draft - unchanged-on-disk proposal derived from that export.
+ * @param program - intended containing program.
+ * @param routine - intended existing routine.
+ * @returns import target and source identity; no Studio import or controller operation occurs.
+ */
+export function studioRoutineImportPlan(baseline, draft, program, routine) {
+    for (const value of [program, routine])
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(value))
+            throw new EngineeringError('INVALID_TARGET', 'Program and routine must be Logix identifiers');
+    const before = documentRoot(parseXml(baseline.xml));
+    const after = documentRoot(parseXml(draft.xml));
+    if (before.attrs.TargetType !== 'Routine' || before.attrs.TargetName !== routine
+        || after.attrs.TargetType !== 'Routine' || after.attrs.TargetName !== routine) {
+        throw new EngineeringError('ROUTINE_COMPONENT_REQUIRED', 'Export the selected routine from the visible IDE first; full controller exports cannot be used as routine import files');
+    }
+    const beforeController = firstChild(before, 'Controller');
+    const afterController = firstChild(after, 'Controller');
+    if (beforeController === undefined || afterController === undefined)
+        throw new EngineeringError('INVALID_COMPONENT', 'Routine export requires controller context');
+    const oldProgram = named(firstChild(beforeController, 'Programs'), 'Program', program);
+    const newProgram = named(firstChild(afterController, 'Programs'), 'Program', program);
+    const oldRoutine = named(firstChild(oldProgram, 'Routines'), 'Routine', routine);
+    const newRoutine = named(firstChild(newProgram, 'Routines'), 'Routine', routine);
+    const protectedNode = (node) => 'children' in node && (node.name === 'EncodedData'
+        || /safety/iu.test(node.attrs.Class ?? '')
+        || Object.entries(node.attrs).some(([key, value]) => /Encrypted|SourceProtected/iu.test(key) && value !== 'false')
+        || node.children.some(protectedNode));
+    if (protectedNode(before) || protectedNode(after) || /safety/iu.test(program))
+        throw new EngineeringError('PROTECTED_TARGET', 'Safety or protected components require the engineer workflow');
+    if (!['RLL', 'ST'].includes(oldRoutine.attrs.Type ?? '') || oldRoutine.attrs.Type !== newRoutine.attrs.Type
+        || oldRoutine.attrs.Use !== 'Target' || newRoutine.attrs.Use !== 'Target')
+        throw new EngineeringError('UNSUPPORTED_TARGET', 'Use an existing unprotected RLL or ST routine exported as Target');
+    if (JSON.stringify(canonical(before, oldRoutine)) !== JSON.stringify(canonical(after, newRoutine)))
+        throw new EngineeringError('UNRELATED_CHANGE', 'Only the selected routine may change; preserve dependency and export context');
+    if (JSON.stringify(canonical(oldRoutine)) === JSON.stringify(canonical(newRoutine)))
+        throw new EngineeringError('NO_CHANGE', 'Routine is unchanged');
+    return {
+        operation: 'studio_ide_routine_import_plan', program, routine, routine_type: newRoutine.attrs.Type,
+        controller_name: beforeController?.attrs.Name ?? null, source_path: baseline.path, source_sha256: baseline.sha256,
+        component_path: draft.path, component_sha256: draft.sha256, software_revision: baseline.softwareRevision,
+        validation: { xml: 'passed', source_and_draft_hashes: 'checked_by_calling_tool', changes_confined_to_routine: true, studio_import: 'not_run', studio_verify: 'not_run', machine_behavior: 'not_verified' },
+        controller_contacted: false, ide_modified: false,
+        steps: ['Observe the same Studio IDE and confirm the saved project, program, routine and offline state.',
+            'Back up the saved project before replacement. Revalidate the proposal immediately before import.',
+            'Navigate to the intended program routine import command using fresh observed UI controls; choose component_path.',
+            'Review the collision preview: replace only this routine, retain existing dependencies, and stop for unexpected changes.',
+            'After import, run Verify in Studio and inspect its diagnostics; unresolved errors block handoff.',
+            'Present the result for engineering review. The engineer performs download; do not accept online edits or change controller mode through UI automation.'],
+    };
+}
+export function routineEditPlan(baseline, draft, program, routine) {
+    for (const value of [program, routine])
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(value))
+            throw new EngineeringError('INVALID_TARGET', 'Program and routine must be Logix identifiers');
+    const before = controller(baseline);
+    const after = controller(draft);
+    const oldProgram = named(firstChild(before, 'Programs'), 'Program', program);
+    const newProgram = named(firstChild(after, 'Programs'), 'Program', program);
+    const tasks = firstChild(before, 'Tasks');
+    const safetyScheduled = tasks !== undefined && elementChildren(tasks, 'Task').some(task => /safety/iu.test(task.attrs.Class ?? '')
+        && firstChild(task, 'ScheduledPrograms')?.children.some(child => 'attrs' in child && child.attrs.Name === program));
+    if (/safety/iu.test(oldProgram.attrs.Class ?? '') || /safety/iu.test(program)
+        || safetyScheduled
+        || baseline.document.tasks.some(task => /safety/iu.test(task.name) && task.programs.includes(program)))
+        throw new EngineeringError('PROTECTED_TARGET', 'Safety programs cannot be imported through the ACD edit tool');
+    const oldRoutine = named(firstChild(oldProgram, 'Routines'), 'Routine', routine);
+    const newRoutine = named(firstChild(newProgram, 'Routines'), 'Routine', routine);
+    if (/safety/iu.test(oldRoutine.attrs.Class ?? '') || /safety/iu.test(newRoutine.attrs.Class ?? ''))
+        throw new EngineeringError('PROTECTED_TARGET', 'Safety routines cannot be edited');
+    if (!['RLL', 'ST'].includes(oldRoutine.attrs.Type ?? '') || oldRoutine.attrs.Type !== newRoutine.attrs.Type)
+        throw new EngineeringError('UNSUPPORTED_TARGET', 'Only existing RLL and ST routines of the same type are supported');
+    const protectedRoutine = (node) => node.name === 'EncodedData'
+        || Object.entries(node.attrs).some(([key, value]) => /Encrypted|SourceProtected/iu.test(key) && value !== 'false')
+        || node.children.some(child => 'children' in child && protectedRoutine(child));
+    if (protectedRoutine(oldRoutine) || protectedRoutine(newRoutine))
+        throw new EngineeringError('PROTECTED_TARGET', 'Encoded or protected routines cannot be edited');
+    const review = reviewDownloadSource(baseline, draft);
+    if (!review.eligible)
+        throw new EngineeringError('EDIT_BLOCKED', review.blockers.join('; '));
+    if (JSON.stringify(canonical(before, oldRoutine)) !== JSON.stringify(canonical(after, newRoutine)))
+        throw new EngineeringError('UNRELATED_CHANGE', 'The draft must change only the selected routine; tags, modules, other logic and controller metadata must remain intact');
+    if (JSON.stringify(canonical(oldRoutine)) === JSON.stringify(canonical(newRoutine)))
+        throw new EngineeringError('NO_CHANGE', 'Selected routine is unchanged');
+    return { xpath: `Controller/Programs/Program[@Name='${program}']/Routines/Routine[@Name='${routine}']` };
+}

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

@@ -0,0 +1,22 @@
+import type { L5xDocument } from '../model/types.ts';
+import type { ProjectSnapshot } from '../session.ts';
+export type Access = 'read' | 'write' | 'read_write' | 'call' | 'unknown';
+export interface Evidence {
+    readonly scope: string;
+    readonly routine: string;
+    readonly language: string;
+    readonly rung?: number;
+    readonly line?: number;
+    readonly sheet?: number;
+    readonly nodeId?: string;
+    readonly symbol: string;
+    readonly resolved?: string;
+    readonly access: Access;
+    readonly confidence: 'high' | 'medium' | 'low';
+    readonly context: string;
+}
+/** Resolve only declarations proven by the export. Never guess an absent member. */
+export declare function resolveSymbol(document: L5xDocument, scope: string, symbol: string): string | undefined;
+export declare function evidenceOf(project: ProjectSnapshot): readonly Evidence[];
+export declare function findReferences(project: ProjectSnapshot, symbol: string, scope?: string): readonly Evidence[];
+export declare function traceSymbol(project: ProjectSnapshot, symbol: string, scope?: string): object;

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

@@ -0,0 +1,258 @@
+import { controllerElementOf } from "../model/parse.js";
+import { elementChildren, firstChild } from "../model/xml.js";
+import { memberOf } from "./details.js";
+const TOKEN = /[A-Za-z_][A-Za-z0-9_]*(?::[A-Za-z0-9_]+)*(?:\[[^\]]+\])?(?:\.[A-Za-z0-9_]+(?:\[[^\]]+\])?)*/gu;
+const LADDER = /([A-Za-z_][A-Za-z0-9_]*)\s*\(([^()]*)\)/gu;
+const READ_OPS = new Set(['XIC', 'XIO', 'EQU', 'EQ', 'NEQ', 'NE', 'GRT', 'GT', 'GEQ', 'GE', 'LES', 'LT', 'LEQ', 'LE', 'LIM', 'LIMIT', 'CMP']);
+const WRITE_OPS = new Set(['OTE', 'OTL', 'OTU', 'CLR']);
+const SOURCE_DEST_OPS = new Set(['MOV', 'MOVE', 'FLL', 'COP', 'ADD', 'SUB', 'MUL', 'DIV']);
+const READ_WRITE_OPS = new Set(['TON', 'TOF', 'RTO', 'CTU', 'CTD', 'RES']);
+const KEYWORDS = new Set(['IF', 'THEN', 'ELSE', 'ELSIF', 'END_IF', 'FOR', 'TO', 'DO', 'END_FOR', 'WHILE', 'END_WHILE', 'RETURN', 'TRUE', 'FALSE', 'AND', 'OR', 'NOT', 'MOD']);
+const BUILTIN_MEMBERS = {
+    TIMER: new Set(['EN', 'TT', 'DN', 'PRE', 'ACC']),
+    TIMER_T: new Set(['EN', 'TT', 'DN', 'PRE', 'ACC']),
+    COUNTER: new Set(['CU', 'CD', 'DN', 'OV', 'UN', 'PRE', 'ACC']),
+};
+/** Integer types that expose bit addresses as `Tag.bit`. */
+const INTEGER_TYPES = new Set(['SINT', 'INT', 'DINT', 'LINT', 'USINT', 'UINT', 'UDINT', 'ULINT']);
+/**
+ * Split instruction operands on top-level commas.
+ *
+ * A two-dimensional subscript such as `Alarm_Timer[0,0].DN` contains a comma
+ * that is not an operand separator; splitting blindly turned that operand into
+ * `Alarm_Timer[0` and `0].DN`, which is where hundreds of false `DN`
+ * references came from.
+ */
+function splitArguments(text) {
+    const parts = [];
+    let depth = 0;
+    let quote = '';
+    let start = 0;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (quote !== '') {
+            if (char === quote)
+                quote = '';
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === '[')
+            depth += 1;
+        else if (char === ']')
+            depth = Math.max(0, depth - 1);
+        else if (char === ',' && depth === 0) {
+            parts.push(text.slice(start, index));
+            start = index + 1;
+        }
+    }
+    parts.push(text.slice(start));
+    return parts.map(part => part.trim());
+}
+const tables = new WeakMap();
+const evidenceCache = new WeakMap();
+function tagKey(scope, name) { return `${scope}::${name.toLowerCase()}`; }
+function aliasElements(container, scope, aliases) {
+    const tags = container === undefined ? undefined : firstChild(container, 'Tags');
+    if (tags === undefined)
+        return;
+    for (const tag of elementChildren(tags, 'Tag')) {
+        const name = tag.attrs['Name'];
+        const target = tag.attrs['AliasFor'];
+        if (name !== undefined && target !== undefined)
+            aliases.set(tagKey(scope, name), target);
+    }
+}
+function tableOf(document) {
+    const cached = tables.get(document);
+    if (cached !== undefined)
+        return cached;
+    const tags = new Map(document.tags.map(tag => [tagKey(tag.scope, tag.name), tag]));
+    const aliases = new Map();
+    const controller = controllerElementOf(document);
+    aliasElements(controller, 'controller', aliases);
+    const programs = firstChild(controller, 'Programs');
+    if (programs !== undefined)
+        for (const program of elementChildren(programs, 'Program')) {
+            aliasElements(program, program.attrs['Name'] ?? '', aliases);
+        }
+    const table = { tags, aliases };
+    tables.set(document, table);
+    return table;
+}
+/** Resolve only declarations proven by the export. Never guess an absent member. */
+export function resolveSymbol(document, scope, symbol) {
+    const table = tableOf(document);
+    const aoi = document.aois.find(entry => entry.name === scope);
+    const parts = symbol.replace(/\[[^\]]+\]/gu, '').split('.');
+    const base = parts.shift();
+    if (base === undefined)
+        return undefined;
+    if (aoi !== undefined && (aoi.parameters.some(p => p.name.toLowerCase() === base.toLowerCase()) || aoi.localTags.some(t => t.name.toLowerCase() === base.toLowerCase()))) {
+        return `${scope}::${symbol}`;
+    }
+    let tag = table.tags.get(tagKey(scope, base)) ?? table.tags.get(tagKey('controller', base));
+    if (tag === undefined)
+        return undefined;
+    let resolvedBase = tag.name;
+    const seen = new Set();
+    while (tag !== undefined) {
+        const key = tagKey(tag.scope, tag.name);
+        const alias = table.aliases.get(key);
+        if (alias === undefined)
+            break;
+        if (seen.has(key))
+            return undefined;
+        seen.add(key);
+        resolvedBase = alias;
+        const aliasBase = alias.split('.')[0];
+        if (aliasBase === undefined)
+            break;
+        tag = table.tags.get(tagKey(tag.scope, aliasBase)) ?? table.tags.get(tagKey('controller', aliasBase));
+        if (tag === undefined)
+            return undefined;
+    }
+    const path = [...resolvedBase.split('.').slice(1), ...parts];
+    if (path.length > 0) {
+        let type = tag?.dataType;
+        for (const [index, part] of path.entries()) {
+            if (/^\d+$/u.test(part)) {
+                // `Alarm[8].12` is bit 12 of an integer element; nothing may follow it.
+                if (index !== path.length - 1 || !INTEGER_TYPES.has(type?.toUpperCase() ?? ''))
+                    return undefined;
+                type = 'BOOL';
+                continue;
+            }
+            if (type !== undefined && BUILTIN_MEMBERS[type.toUpperCase()]?.has(part.toUpperCase())) {
+                if (index !== path.length - 1)
+                    return undefined;
+                continue;
+            }
+            const aoiDefinition = document.aois.find(entry => entry.name.toLowerCase() === type?.toLowerCase());
+            if (aoiDefinition !== undefined) {
+                const member = aoiDefinition.parameters.find(entry => entry.name.toLowerCase() === part.toLowerCase())
+                    ?? aoiDefinition.localTags.find(entry => entry.name.toLowerCase() === part.toLowerCase());
+                if (member === undefined)
+                    return undefined;
+                type = member.dataType;
+                continue;
+            }
+            const member = memberOf(document, type ?? '', part);
+            if (member === undefined)
+                return undefined;
+            type = member.dataType;
+        }
+    }
+    return `${tag?.scope ?? scope}::${resolvedBase}${parts.length > 0 ? `.${parts.join('.')}` : ''}`;
+}
+function tokens(text) { return [...text.matchAll(TOKEN)].map(match => match[0]).filter(token => !KEYWORDS.has(token.toUpperCase()) && !/^\d/u.test(token)); }
+function add(out, document, routine, symbol, access, context, location, confidence) {
+    const resolved = resolveSymbol(document, routine.program, symbol);
+    out.push({ scope: routine.program, routine: routine.name, language: routine.type, ...location, symbol, ...(resolved === undefined ? {} : { resolved }), access, confidence, context });
+}
+function ladderEvidence(out, document, routine, text, rung) {
+    for (const match of text.matchAll(LADDER)) {
+        const op = match[1]?.toUpperCase() ?? '';
+        const args = splitArguments(match[2] ?? '');
+        if (op === 'JSR') {
+            const target = args[0] ?? '';
+            const called = document.routines.find(entry => entry.program === routine.program && entry.name.toLowerCase() === target.toLowerCase());
+            out.push({ scope: routine.program, routine: routine.name, language: routine.type, rung, symbol: target, ...(called === undefined ? {} : { resolved: `${called.program}::${called.name}` }), access: 'call', confidence: called === undefined ? 'low' : 'high', context: text });
+            continue;
+        }
+        const aoi = document.aois.find(entry => entry.name.toUpperCase() === op);
+        if (aoi !== undefined) {
+            out.push({ scope: routine.program, routine: routine.name, language: routine.type, rung, symbol: aoi.name, resolved: `AOI::${aoi.name}`, access: 'call', confidence: 'high', context: text });
+            const visible = aoi.parameters.filter(parameter => parameter.visible !== false && parameter.name !== 'EnableIn' && parameter.name !== 'EnableOut');
+            const positional = args.length === visible.length + 1;
+            for (const [index, arg] of args.entries()) {
+                const usage = positional && index > 0 ? visible[index - 1]?.usage : undefined;
+                const access = index === 0 ? 'read_write' : usage === 'Input' ? 'read' : usage === 'Output' ? 'write' : usage === 'InOut' ? 'read_write' : 'unknown';
+                for (const symbol of tokens(arg ?? ''))
+                    add(out, document, routine, symbol, access, text, { rung }, usage === undefined ? 'low' : 'medium');
+            }
+            continue;
+        }
+        for (const [index, arg] of args.entries()) {
+            const destination = op === 'COP' || op === 'FLL' ? 1 : args.length - 1;
+            const access = READ_OPS.has(op) ? 'read' : WRITE_OPS.has(op) ? 'write' : SOURCE_DEST_OPS.has(op) ? (index === destination ? 'write' : 'read') : READ_WRITE_OPS.has(op) ? 'read_write' : 'unknown';
+            for (const symbol of tokens(arg ?? ''))
+                add(out, document, routine, symbol, access, text, { rung }, access === 'unknown' ? 'low' : 'medium');
+        }
+    }
+}
+function structuredEvidence(out, document, routine, code) {
+    // Keep offsets and line positions while excluding strings and multiline comments.
+    const text = code.replace(/\(\*[\s\S]*?\*\)|\/\*[\s\S]*?\*\/|\/\/[^\n]*|'(?:\$[\s\S]|''|[^'])*'|"(?:\$[\s\S]|""|[^"])*"/gu, value => value.replace(/[^\n]/gu, ' '));
+    let start = 0;
+    for (const statement of text.split(';')) {
+        const assignment = statement.indexOf(':=');
+        const target = assignment < 0 ? undefined : /([A-Za-z_][A-Za-z0-9_.]*(?:\[[^\]]+\])?)\s*$/u.exec(statement.slice(0, assignment));
+        const targetStart = target === undefined || target === null ? -1 : target.index;
+        const ambiguous = assignment >= 0 && statement.indexOf(':=', assignment + 2) >= 0;
+        for (const match of statement.matchAll(TOKEN)) {
+            const symbol = match[0];
+            if (KEYWORDS.has(symbol.toUpperCase()) || /^(?:BY|END_FOR|REPEAT|UNTIL|END_REPEAT|CASE|OF|END_CASE|EXIT|END_WHILE)$/iu.test(symbol))
+                continue;
+            const call = /^\s*\(/u.test(statement.slice(match.index + symbol.length));
+            const indexed = symbol.includes('[');
+            const access = ambiguous || call || indexed ? 'unknown'
+                : assignment >= 0 && match.index === targetStart ? 'write' : 'read';
+            const line = text.slice(0, start + match.index).split('\n').length - 1;
+            add(out, document, routine, symbol, access, code.split('\n')[line]?.trim() ?? '', { line }, access === 'unknown' ? 'low' : 'medium');
+        }
+        start += statement.length + 1;
+    }
+}
+export function evidenceOf(project) {
+    const cached = evidenceCache.get(project);
+    if (cached !== undefined)
+        return cached;
+    const out = [];
+    const routines = [...project.document.routines, ...project.document.aois.flatMap(aoi => aoi.routines)];
+    for (const routine of routines) {
+        if (routine.body.type === 'RLL') {
+            for (const rung of routine.body.rungs)
+                ladderEvidence(out, project.document, routine, rung.text, rung.number);
+        }
+        else if (routine.body.type === 'ST') {
+            structuredEvidence(out, project.document, routine, routine.body.code);
+        }
+        else if (routine.body.type === 'FBD' || routine.body.type === 'SFC') {
+            for (const node of routine.body.nodes) {
+                const expression = node.operand ?? (node.kind === 'Line' ? node.text : undefined);
+                if (expression === undefined)
+                    continue;
+                const access = node.kind === 'IRef' ? 'read' : node.kind === 'ORef' ? 'write' : 'unknown';
+                for (const symbol of tokens(expression))
+                    add(out, project.document, routine, symbol, access, `${node.kind} sheet ${node.sheet} id ${node.id ?? '?'}`, { sheet: node.sheet, ...(node.id === undefined ? {} : { nodeId: node.id }) }, access === 'unknown' ? 'low' : 'medium');
+            }
+        }
+    }
+    evidenceCache.set(project, out);
+    return out;
+}
+export function findReferences(project, symbol, scope) {
+    const query = symbol.toLowerCase();
+    return evidenceOf(project).filter(entry => (scope === undefined || entry.scope === scope) && (entry.symbol.toLowerCase() === query || entry.symbol.toLowerCase().startsWith(`${query}.`) ||
+        entry.resolved?.toLowerCase() === query || entry.resolved?.toLowerCase().endsWith(`::${query}`) ||
+        entry.resolved?.toLowerCase().includes(`::${query}.`)));
+}
+export function traceSymbol(project, symbol, scope) {
+    const references = findReferences(project, symbol, scope);
+    const writers = references.filter(r => r.access === 'write' || r.access === 'read_write');
+    const all = evidenceOf(project);
+    const originCandidates = writers.map(writer => ({
+        writer,
+        inputsAtLocation: all.filter(ref => ref.scope === writer.scope && ref.routine === writer.routine && ref.rung === writer.rung && ref.line === writer.line && ref.sheet === writer.sheet && ref.access === 'read'),
+    }));
+    return {
+        symbol, references, writers, originCandidates,
+        readers: references.filter(r => r.access === 'read' || r.access === 'read_write'),
+        complete: false,
+        classification_complete: references.length > 0 && references.every(r => r.access !== 'unknown' && r.resolved !== undefined) && project.features.functionBlock !== 'partial' && project.features.sequentialFunctionChart !== 'partial',
+        note: 'Inputs at a writer location are candidates, not proven causal or runtime data flow. External controller behavior is not analyzed.',
+    };
+}

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

@@ -0,0 +1,9 @@
+/** Capability guidance separates offline analysis, SDK builds and live diagnostics. */
+import type { SdkStatus } from './studio-sdk.ts';
+import type { ProjectSnapshot } from '../session.ts';
+/** Resolve an installed SDK report against the selected export revision.
+ * @param sdk - local dependency observations, without controller contact.
+ * @param project - optional selected export.
+ * @returns capability availability and concrete workflow steps.
+ */
+export declare function engineeringCapabilities(sdk: SdkStatus, project?: ProjectSnapshot): object;

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

@@ -0,0 +1,40 @@
+/** The SDK opens projects at these revisions. */
+const OPEN_MINIMUM = 31;
+/** Build is a Logix Designer project-revision feature, not an installed-app feature. */
+const BUILD_MINIMUM = 37;
+/** Resolve an installed SDK report against the selected export revision.
+ * @param sdk - local dependency observations, without controller contact.
+ * @param project - optional selected export.
+ * @returns capability availability and concrete workflow steps.
+ */
+export function engineeringCapabilities(sdk, project) {
+    const revision = project === undefined ? undefined : Number.parseInt(project.softwareRevision, 10);
+    // The SDK opens a project with the Logix Designer release matching its revision,
+    // so an installed copy of that exact revision is required.
+    const matching = revision === undefined || sdk.installed_studio_versions.includes(revision);
+    const opening = sdk.available && matching && (revision === undefined || revision >= OPEN_MINIMUM);
+    const build = opening && (revision === undefined || revision >= BUILD_MINIMUM);
+    const versionAxes = {
+        engine_selected_by: 'project_revision',
+        open_supported_project_revisions: `>= ${OPEN_MINIMUM}`,
+        build_supported_project_revisions: `>= ${BUILD_MINIMUM}`,
+        sdk_release: sdk.sdk_release,
+        installed_logix_designer_releases: sdk.installed_studio_versions,
+        observed_build_refusal: 'Operation not supported on Logix Designer version 36.0',
+    };
+    return {
+        observed_at: new Date().toISOString(), controller_contacted: false,
+        project_revision: project?.softwareRevision ?? null, sdk, version_axes: versionAxes,
+        capabilities: {
+            l5x_analysis: { available: true, tools: ['open_project', 'project_overview', 'get_component', 'find_references', 'trace_symbol', 'run_checks', 'compare_projects'] },
+            parsed_analysis: { available: true, tools: ['resolve_tag', 'analyze_project', 'find_parsed_references', 'trace_signal', 'analyze_impact', 'project_execution_graph'], runtime_causality: 'unverified', diagram_execution: 'unsupported' },
+            draft_editing: { available: true, tools: ['propose_change', 'validate_proposal', 'prepare_change_set', 'validate_change_set', 'apply_change_set', 'propose_udt_change'], studio_validation: 'required', coordinated_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'] },
+            references: { available: true, tools: ['rockwell_reference_sources', 'rockwell_reference_sync', 'rockwell_reference_search'], downloads_optional: true },
+            acd_export: { available: opening, next_step: opening ? 'Export the selected ACD to a new L5X and open it.' : 'Export an L5X manually in the matching Studio 5000 version; continue offline analysis.' },
+            offline_build: { available: build, project_selected: project !== undefined, requires_project_revision: BUILD_MINIMUM, probe_tool: 'verify_offline_l5x with probe=true', next_step: build ? 'Review a full baseline and draft, then verify_offline_l5x or edit_offline_acd.' : `Use Studio 5000 Import + Verify manually. Build is supported only for project revision ${BUILD_MINIMUM}+ because the SDK selects the engine by project revision; probe=true attempts it and reports the SDK error.` },
+            live_diagnostics: { available: opening && sdk.live_communications_available === true, tools: ['read_controller_mode', 'read_live_tag', 'sample_live_tags', 'observe_logic'], next_step: opening && sdk.live_communications_available ? 'Obtain explicit controller IP and use a matching uploaded ACD snapshot.' : 'Continue offline inspection; resolve SDK and FactoryTalk Linx dependencies before live reads.' },
+            controller_transfers: { available: opening && sdk.live_communications_available === true, approval: 'per-operation human approval required; call controller_approval_status', download: 'verified artifact and Program mode required' },
+        },
+        limitation: revision === undefined ? 'Select an export to verify its revision against installed Studio versions.' : !matching ? `Matching Studio ${revision} is not installed; the SDK opens a project with the release matching its revision.` : !sdk.available ? sdk.reason : null,
+    };
+}

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

@@ -0,0 +1,122 @@
+import { type ProjectSnapshot } from '../session.ts';
+type Operation = {
+    readonly operation: 'replace_rung';
+    readonly program: string;
+    readonly routine: string;
+    readonly rung: number;
+    readonly text: string;
+} | {
+    readonly operation: 'delete_rung';
+    readonly program: string;
+    readonly routine: string;
+    readonly rung: number;
+} | {
+    readonly operation: 'insert_rung';
+    readonly program: string;
+    readonly routine: string;
+    readonly rung: number;
+    readonly text: string;
+    readonly before_rung?: number;
+} | {
+    readonly operation: 'replace_st';
+    readonly program: string;
+    readonly routine: string;
+    readonly code: string;
+} | {
+    readonly operation: 'add_routine';
+    readonly program: string;
+    readonly name: string;
+    readonly language: 'RLL' | 'ST';
+    readonly code: string;
+} | {
+    readonly operation: 'add_tag';
+    readonly scope: string;
+    readonly name: string;
+    readonly data_type: string;
+    readonly value?: number;
+    readonly dimensions?: string;
+    readonly external_access?: string;
+    readonly description: string;
+} | {
+    readonly operation: 'set_tag_description';
+    readonly scope: string;
+    readonly name: string;
+    readonly description: string;
+} | {
+    readonly operation: 'add_udt_member';
+    readonly udt: string;
+    readonly name: string;
+    readonly data_type: string;
+    readonly description: string;
+} | {
+    readonly operation: 'set_udt_description';
+    readonly udt: string;
+    readonly description: string;
+} | {
+    readonly operation: 'set_udt_member_description';
+    readonly udt: string;
+    readonly member: string;
+    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\"}]}";
+/** Limits are resolved by the plugin's configuration before tools call this module. */
+export interface ChangeSetLimits {
+    readonly operations: number;
+    readonly bytes: number;
+}
+/** One prepared draft and its review data. */
+export interface PreparedChangeSet {
+    readonly xml: string;
+    readonly operations: readonly Operation[];
+    readonly source_sha256: string;
+    readonly draft_sha256: string;
+    readonly diff: unknown;
+    readonly checks: unknown;
+    readonly validation: {
+        readonly xml: string;
+        readonly studio_import: string;
+        readonly studio_build: string;
+        readonly behavior: string;
+    };
+    readonly prepared: 'computed' | 'cache';
+}
+/** Prepare every operation in memory, without writing a draft or touching Studio.
+ * @param project - Hash-verified baseline.
+ * @param request - Version-1 JSON change set.
+ * @param limits - Validated operation and draft-size limits.
+ * @returns Draft text and review data; malformed, unsupported or protected changes throw.
+ */
+export declare function prepareChangeSet(project: ProjectSnapshot, request: string, limits: ChangeSetLimits): PreparedChangeSet;
+/** One changed data type as a Studio Data Type import component.
+ * @param project - Hash-verified baseline.
+ * @param request - Version-1 JSON change set holding one or more UDT operations.
+ * @returns Component L5X text plus the type-level difference; no file is written.
+ */
+export declare function prepareUdtComponent(project: ProjectSnapshot, request: string): {
+    xml: string;
+    operations: readonly Operation[];
+    udt: string;
+    source_sha256: string;
+    component_sha256: string;
+    changes: {
+        before: import("../model/types.ts").L5xUdt;
+        after: import("../model/types.ts").L5xUdt;
+    };
+    validation: {
+        xml: string;
+        studio_import: "not_run";
+    };
+};
+export {};
+/** Stage a fully prepared change set into a new file, retaining proposal validation compatibility.
+ * @param ctx - Filesystem service.
+ * @param session - Calling chat's project/proposal records.
+ * @param project - Current source snapshot.
+ * @param request - Version-1 operations JSON.
+ * @param outputPath - New draft beside the source.
+ * @param expectedHash - Baseline hash reviewed during preparation.
+ * @param limits - Operation and byte limits.
+ * @param signal - Cancellation for filesystem operations.
+ * @returns Proposal identity, hash-bound changes and static validation; no SDK or controller operations.
+ */