@aryacode/dsh-engineering 0.0.0-stage → 0.4.0

package/vendor/l5x/lib/engine/logic-syntax.js

@@ -0,0 +1,237 @@
+/** Source-positioned Logix tokens and NeutralText structure for static analysis. */
+/** Tokenize Logix source without treating comments or quoted literals as symbols.
+ * @param source - Original routine or rung text.
+ * @returns Source tokens and lexical issues; newlines in comments and literals retain their positions.
+ */
+export function lexLogic(source) {
+    const tokens = [];
+    const issues = [];
+    let cursor = 0;
+    let line = 0;
+    const advance = () => { if (source[cursor] === '\n')
+        line++; cursor++; };
+    while (cursor < source.length) {
+        const char = source[cursor];
+        if (/\s/u.test(char)) {
+            advance();
+            continue;
+        }
+        if (source.startsWith('//', cursor)) {
+            while (cursor < source.length && source[cursor] !== '\n')
+                advance();
+            continue;
+        }
+        if (source.startsWith('(*', cursor) || source.startsWith('/*', cursor)) {
+            const start = cursor;
+            const close = source.startsWith('(*', cursor) ? '*)' : '*/';
+            advance();
+            advance();
+            while (cursor < source.length && !source.startsWith(close, cursor))
+                advance();
+            if (cursor === source.length)
+                issues.push({ offset: start, message: 'Unterminated block comment' });
+            else {
+                advance();
+                advance();
+            }
+            continue;
+        }
+        const start = cursor;
+        const firstLine = line;
+        let kind = 'punctuation';
+        if (char === "'" || char === '"') {
+            kind = 'string';
+            advance();
+            let closed = false;
+            while (cursor < source.length) {
+                if (source[cursor] === '$') {
+                    advance();
+                    if (cursor < source.length)
+                        advance();
+                    continue;
+                }
+                if (source[cursor] === char) {
+                    advance();
+                    if (source[cursor] === char) {
+                        advance();
+                        continue;
+                    }
+                    closed = true;
+                    break;
+                }
+                advance();
+            }
+            if (!closed)
+                issues.push({ offset: start, message: 'Unterminated string literal' });
+        }
+        else if (/[A-Za-z_]/u.test(char)) {
+            kind = 'identifier';
+            while (cursor < source.length && /[A-Za-z0-9_]/u.test(source[cursor]))
+                advance();
+        }
+        else if (/[0-9]/u.test(char)) {
+            kind = 'number';
+            while (cursor < source.length && /[0-9A-Fa-f_#]/u.test(source[cursor]))
+                advance();
+        }
+        else {
+            advance();
+            if ([':=', '<=', '>=', '<>', '**'].includes(source.slice(start, cursor + 1)))
+                advance();
+        }
+        tokens.push({ kind, text: source.slice(start, cursor), start, end: cursor, line: firstLine });
+    }
+    return { tokens, issues };
+}
+/** Parse standard NeutralText instructions and nested parallel branches.
+ * @param source - One complete rung, including its terminator.
+ * @returns Parsed nodes and located issues; malformed structure is never silently complete.
+ */
+export function parseLadder(source) {
+    const lexical = lexLogic(source);
+    const tokens = lexical.tokens;
+    const issues = [...lexical.issues];
+    let cursor = 0;
+    const sequence = (depth) => {
+        const nodes = [];
+        if (depth > 128) {
+            issues.push({ offset: tokens[cursor]?.start ?? source.length, message: 'Branch nesting exceeds the parser limit' });
+            cursor = tokens.length;
+            return nodes;
+        }
+        while (cursor < tokens.length) {
+            const token = tokens[cursor];
+            if (token.text === ']' || token.text === ',')
+                break;
+            if (token.kind === 'identifier' && ['NXB', 'BND'].includes(token.text.toUpperCase()))
+                break;
+            if (token.text === ';') {
+                cursor++;
+                if (cursor < tokens.length)
+                    issues.push({ offset: token.start, message: 'Content after rung terminator' });
+                break;
+            }
+            if (token.text === '[') {
+                cursor++;
+                const paths = [];
+                paths.push(sequence(depth + 1));
+                while (tokens[cursor]?.text === ',') {
+                    cursor++;
+                    paths.push(sequence(depth + 1));
+                }
+                const close = tokens[cursor];
+                if (close?.text !== ']') {
+                    issues.push({ offset: token.start, message: 'Unterminated ladder branch' });
+                    break;
+                }
+                cursor++;
+                if (paths.length < 2 || paths.some(path => path.length === 0))
+                    issues.push({ offset: token.start, message: 'Branch requires nonempty parallel paths' });
+                nodes.push({ kind: 'branch', paths, start: token.start, end: close.end });
+                continue;
+            }
+            if (token.kind === 'identifier' && token.text.toUpperCase() === 'BST') {
+                cursor++;
+                const paths = [sequence(depth + 1)];
+                while (tokens[cursor]?.text.toUpperCase() === 'NXB') {
+                    cursor++;
+                    paths.push(sequence(depth + 1));
+                }
+                const close = tokens[cursor];
+                if (close?.text.toUpperCase() !== 'BND') {
+                    issues.push({ offset: token.start, message: 'Unterminated BST branch' });
+                    break;
+                }
+                cursor++;
+                if (paths.length < 2 || paths.some(path => path.length === 0))
+                    issues.push({ offset: token.start, message: 'Branch requires nonempty parallel paths' });
+                nodes.push({ kind: 'branch', paths, start: token.start, end: close.end });
+                continue;
+            }
+            if (token.kind !== 'identifier' || tokens[cursor + 1]?.text !== '(') {
+                issues.push({ offset: token.start, message: `Unsupported ladder token ${token.text}` });
+                cursor++;
+                continue;
+            }
+            cursor += 2;
+            const operands = [[]];
+            let parentheses = 1;
+            let brackets = 0;
+            let end = token.end;
+            while (cursor < tokens.length) {
+                const operand = tokens[cursor++];
+                if (operand.text === '(')
+                    parentheses++;
+                if (operand.text === ')')
+                    parentheses--;
+                if (parentheses === 0) {
+                    end = operand.end;
+                    break;
+                }
+                if (operand.text === '[')
+                    brackets++;
+                if (operand.text === ']')
+                    brackets--;
+                if (operand.text === ',' && parentheses === 1 && brackets === 0)
+                    operands.push([]);
+                else
+                    operands[operands.length - 1].push(operand);
+            }
+            if (parentheses !== 0 || brackets !== 0)
+                issues.push({ offset: token.start, message: 'Unbalanced instruction operands' });
+            nodes.push({ kind: 'instruction', name: token.text, operands: operands.length === 1 && operands[0].length === 0 ? [] : operands, start: token.start, end });
+        }
+        return nodes;
+    };
+    const nodes = sequence(0);
+    if (cursor !== tokens.length)
+        issues.push({ offset: tokens[cursor].start, message: 'Unexpected branch delimiter' });
+    if (tokens[tokens.length - 1]?.text !== ';')
+        issues.push({ offset: source.length, message: 'Missing rung terminator' });
+    return { nodes, issues };
+}
+/** Read an identifier with optional program qualification, member paths and indices.
+ * @param tokens - Source-positioned tokens.
+ * @param offset - Index of the address's first identifier.
+ * @returns The address and next token index, or undefined for malformed indices.
+ */
+export function addressAt(tokens, offset) {
+    const first = tokens[offset];
+    if (first?.kind !== 'identifier')
+        return undefined;
+    let cursor = offset + 1;
+    let text = first.text;
+    const indexTokens = [];
+    if (first.text.toLowerCase() === 'program' && tokens[cursor]?.text === ':' && tokens[cursor + 1]?.kind === 'identifier' && tokens[cursor + 2]?.text === '.') {
+        text += `:${tokens[cursor + 1].text}.`;
+        cursor += 3;
+        if (tokens[cursor]?.kind !== 'identifier')
+            return undefined;
+        text += tokens[cursor++].text;
+    }
+    while (cursor < tokens.length) {
+        if (tokens[cursor]?.text === '[') {
+            let depth = 1;
+            text += tokens[cursor++].text;
+            while (cursor < tokens.length && depth > 0) {
+                const token = tokens[cursor++];
+                if (token.text === '[')
+                    depth++;
+                if (token.text === ']')
+                    depth--;
+                text += token.text;
+                if (depth > 0)
+                    indexTokens.push(token);
+            }
+            if (depth !== 0)
+                return undefined;
+        }
+        else if (tokens[cursor]?.text === '.' && ['identifier', 'number'].includes(tokens[cursor + 1]?.kind ?? '')) {
+            text += `.${tokens[cursor + 1].text}`;
+            cursor += 2;
+        }
+        else
+            break;
+    }
+    return { address: { text, start: first.start, end: tokens[cursor - 1].end, line: first.line, indexTokens }, next: cursor };
+}

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

@@ -0,0 +1,41 @@
+/** Bind bounded live samples to source evidence; only simple series BOOL contacts are evaluated. */
+import { type Evidence } from './analysis.ts';
+import { type ProjectSnapshot } from '../session.ts';
+import type { LiveWatchTag } from './studio-sdk.ts';
+/** A sweep returned by the SDK with per-tag quality and actual timestamps. */
+export interface LogicSample {
+    elapsed_ms: number;
+    sweep_ms: number;
+    values: {
+        tag: string;
+        value: string | number | boolean | null;
+        quality: string;
+        observed_at: string;
+        error?: string;
+    }[];
+}
+/** Choose controller scalar tags referenced by exactly one selected routine.
+ * @param project - verified export snapshot.
+ * @param program - exact program name.
+ * @param routine - exact routine name.
+ * @param selected - optional explicit subset of tag names.
+ * @returns bounded watch candidates and unresolved evidence; never truncates a watch silently.
+ */
+export declare function logicWatch(project: ProjectSnapshot, program: string, routine: string, selected?: readonly string[]): {
+    program: string;
+    routine: string;
+    language: string;
+    tags: LiveWatchTag[];
+    unresolved: Evidence[];
+    evidence: Evidence[];
+    sampling_available: boolean;
+    next_step: string;
+};
+/** Explain only supported series contacts; sequential reads cannot establish runtime causality.
+ * @param project - source export.
+ * @param program - selected program.
+ * @param routine - selected routine.
+ * @param samples - timestamped SDK sweeps.
+ * @returns contacts failing their observed conditions and explicit unresolved rungs.
+ */
+export declare function explainLogicSamples(project: ProjectSnapshot, program: string, routine: string, samples: readonly LogicSample[]): object;

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

@@ -0,0 +1,67 @@
+/** Bind bounded live samples to source evidence; only simple series BOOL contacts are evaluated. */
+import { evidenceOf } from "./analysis.js";
+import { EngineeringError } from "../session.js";
+import { aliasesOf } from "./configuration.js";
+/** Choose controller scalar tags referenced by exactly one selected routine.
+ * @param project - verified export snapshot.
+ * @param program - exact program name.
+ * @param routine - exact routine name.
+ * @param selected - optional explicit subset of tag names.
+ * @returns bounded watch candidates and unresolved evidence; never truncates a watch silently.
+ */
+export function logicWatch(project, program, routine, selected) {
+    const body = project.document.routines.find(entry => entry.program === program && entry.name === routine);
+    if (body === undefined)
+        throw new EngineeringError('COMPONENT_NOT_FOUND', 'Select an existing program and routine');
+    const evidence = evidenceOf(project).filter(entry => entry.scope === program && entry.routine === routine);
+    const tags = [];
+    const unresolved = [];
+    for (const entry of evidence) {
+        const tag = project.document.tags.find(candidate => candidate.scope === 'controller' && entry.resolved === `controller::${candidate.name}`);
+        if (tag === undefined || aliasesOf(project.document).has(`controller::${tag.name}`) || !['BOOL', 'INT', 'DINT', 'REAL'].includes(tag.dataType)) {
+            unresolved.push(entry);
+            continue;
+        }
+        if (selected !== undefined && !selected.some(name => name.toLowerCase() === tag.name.toLowerCase()))
+            continue;
+        if (!tags.some(item => item.name.toLowerCase() === tag.name.toLowerCase())) {
+            const type = tag.dataType;
+            if (type === 'BOOL' || type === 'INT' || type === 'DINT' || type === 'REAL')
+                tags.push({ name: tag.name, data_type: type });
+        }
+    }
+    if (selected !== undefined && (selected.length === 0 || selected.some(name => !tags.some(tag => tag.name.toLowerCase() === name.toLowerCase()))))
+        throw new EngineeringError('INVALID_WATCH', 'Every selected tag must be a controller scalar referenced by this routine');
+    return { program, routine, language: body.type, tags, unresolved, evidence,
+        sampling_available: tags.length > 0 && tags.length <= 16,
+        next_step: tags.length > 16 ? 'Select at most 16 tag names using tags_json; all candidates are shown.' : tags.length === 0 ? 'This routine has no supported controller scalar candidates; inspect unresolved evidence.' : 'Use observe_logic with sample_count and interval_ms to sample this watch.' };
+}
+/** Explain only supported series contacts; sequential reads cannot establish runtime causality.
+ * @param project - source export.
+ * @param program - selected program.
+ * @param routine - selected routine.
+ * @param samples - timestamped SDK sweeps.
+ * @returns contacts failing their observed conditions and explicit unresolved rungs.
+ */
+export function explainLogicSamples(project, program, routine, samples) {
+    const body = project.document.routines.find(entry => entry.program === program && entry.name === routine)?.body;
+    const observations = samples.map(sample => {
+        const conditions = body?.type !== 'RLL' ? [] : body.rungs.map(rung => {
+            const supported = /^(?:XIC\([A-Za-z_][A-Za-z0-9_]*\)|XIO\([A-Za-z_][A-Za-z0-9_]*\))+OTE\([A-Za-z_][A-Za-z0-9_]*\);?$/u.test(rung.text.trim());
+            if (!supported)
+                return { rung: rung.number, status: 'unresolved', reason: 'Only series XIC/XIO contacts ending in OTE are evaluated; branches and other instructions need review.' };
+            const contacts = [...rung.text.matchAll(/(XIC|XIO)\(([A-Za-z_][A-Za-z0-9_]*)\)/gu)].map(match => {
+                const symbol = match[2] ?? '';
+                // A program tag shadows a controller tag of the same name.
+                const scoped = project.document.tags.some(tag => tag.scope === program && tag.name.toLowerCase() === symbol.toLowerCase());
+                const reading = scoped ? undefined : sample.values.find(value => value.tag.toLowerCase() === symbol.toLowerCase());
+                const boolean = reading?.quality === 'good' ? reading.value === true || reading.value === 'true' ? true : reading.value === false || reading.value === 'false' ? false : undefined : undefined;
+                return { symbol, instruction: match[1], value: boolean ?? null, condition: boolean === undefined ? 'unknown' : boolean === (match[1] === 'XIC') ? 'met' : 'not_met' };
+            });
+            return { rung: rung.number, status: contacts.some(contact => contact.condition === 'unknown') ? 'unresolved' : 'observed', contacts, unmet_contacts: contacts.filter(contact => contact.condition === 'not_met').map(contact => contact.symbol) };
+        });
+        return { elapsed_ms: sample.elapsed_ms, sweep_ms: sample.sweep_ms, conditions };
+    });
+    return { observations, evaluation: body?.type === 'RLL' ? 'limited_series_contacts' : 'source_evidence_only',
+        limitation: 'Sequential point-in-time samples can miss transitions. Contact observations do not prove execution, scheduling, output state, or the root cause. Export logic may differ from online logic.' };
+}

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

@@ -0,0 +1,131 @@
+import type { ProjectSnapshot } from '../session.ts';
+/** Stable location within the source snapshot identified by its project hash. */
+export interface SourceLocation {
+    readonly scope: string;
+    readonly routine: string;
+    readonly language: string;
+    readonly rung?: number;
+    readonly line?: number;
+    readonly start: number;
+    readonly end: number;
+}
+/** One source occurrence, with an operand classification and declaration resolution. */
+export interface ParsedReference extends SourceLocation {
+    readonly symbol: string;
+    readonly canonical?: string;
+    readonly access: 'read' | 'write' | 'read_write' | 'call' | 'unknown';
+    readonly instruction?: string;
+    readonly indices_verified: boolean;
+    readonly context: string;
+}
+/** A located limitation that prevents a claim of complete static coverage. */
+export interface AnalysisLimitation {
+    readonly scope: string;
+    readonly routine: string;
+    readonly rung?: number;
+    readonly offset?: number;
+    readonly reason: string;
+}
+/** Edge evidence uses indices into the containing analysis's reference array. */
+export interface DependencyEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: 'operand' | 'condition_candidate';
+    readonly evidence: readonly number[];
+}
+/** Shared result for model tools and other consumers. */
+export interface ProjectAnalysis {
+    readonly project_id: string;
+    readonly source_sha256: string;
+    readonly references: readonly ParsedReference[];
+    readonly dependencies: readonly DependencyEdge[];
+    readonly limitations: readonly AnalysisLimitation[];
+    readonly static_complete: boolean;
+    readonly runtime_causality_verified: false;
+}
+/** Deployment limits prevent dense logic from producing unbounded reference and edge arrays. */
+export interface AnalysisBounds {
+    readonly references: number;
+    readonly edges: number;
+}
+/** Registry version changes when operand roles change. It does not certify controller availability. */
+export declare const SEMANTICS_VERSION = 1;
+/** Build source-positioned references and conservative local dependency edges once per snapshot.
+ * @param project - Immutable export snapshot.
+ * @param bounds - Inclusive reference and edge limits; truncation makes coverage incomplete.
+ * @returns Shared analysis with located limitations and source identity.
+ */
+export declare function analyzeProject(project: ProjectSnapshot, bounds: AnalysisBounds): ProjectAnalysis;
+/** Read exported task scheduling, program entry routines and parsed JSR/AOI call locations.
+ * @param project - Immutable selected export.
+ * @param limits - Deployment bounds for graph size and source analysis.
+ * @returns A bounded execution graph; declared scheduling is not observed scan execution.
+ */
+export declare function executionGraph(project: ProjectSnapshot, limits: TraceLimits): {
+    project_id: string;
+    source_sha256: string;
+    nodes: {
+        identity: string;
+        kind: "task" | "program" | "routine" | "aoi";
+        declared: boolean;
+    }[];
+    edges: {
+        from: string;
+        to: string;
+        kind: "schedules" | "entry" | "call";
+        evidence?: ParsedReference;
+    }[];
+    truncated: boolean;
+    unscheduled_programs: string[];
+    static_complete: boolean;
+    runtime_execution_verified: boolean;
+};
+/** Bounds for a breadth-first static dependency traversal. */
+export interface TraceLimits {
+    readonly depth: number;
+    readonly nodes: number;
+    readonly edges: number;
+    readonly analysis: AnalysisBounds;
+}
+/** Trace dependencies or dependents, returning every stopping reason.
+ * @param project - Immutable selected source.
+ * @param symbol - Selected tag address.
+ * @param scope - Its resolution scope.
+ * @param direction - Upstream sources or downstream impact.
+ * @param limits - Validated deployment bounds.
+ * @returns Bounded graph with source-linked edges, coverage and truncation indicators.
+ */
+export declare function traceDependencies(project: ProjectSnapshot, symbol: string, scope: string, direction: 'upstream' | 'downstream', limits: TraceLimits): {
+    truncated: boolean;
+    static_complete: boolean;
+    runtime_causality_verified: boolean;
+    limitations: AnalysisLimitation[];
+    limitations_total: number;
+    limitations_truncated: boolean;
+    project_id: string;
+    source_sha256: string;
+    resolution: import("./tag-resolution.ts").TagResolution;
+    nodes: never[];
+    edges: never[];
+} | {
+    truncated: boolean;
+    static_complete: boolean;
+    runtime_causality_verified: boolean;
+    limitations: AnalysisLimitation[];
+    limitations_total: number;
+    limitations_truncated: boolean;
+    project_id: string;
+    source_sha256: string;
+    resolution: import("./tag-resolution.ts").TagResolution;
+    direction: "upstream" | "downstream";
+    nodes: {
+        symbol: string;
+        depth: number;
+    }[];
+    edges: {
+        evidence: ParsedReference[];
+        from: string;
+        to: string;
+        kind: "operand" | "condition_candidate";
+    }[];
+};