@aryacode/dsh-engineering 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,245 @@
+/**
+ * The offline read surface: open, look, and read one component.
+ *
+ * Every tool answers with the same document — `summary`, `data`, optional
+ * `coverage`, and concrete `next` calls — and every expected failure answers
+ * with a code, a message and a fix. The tool descriptions name the one intent
+ * each tool serves; parameters carry their own meaning and an example.
+ *
+ * @module dsh-engineering-l5x/tools/read
+ */
+import { getAoi, getRoutine, getUdt, listAois, listModules, listRoutines, listTags } from "../model/index.js";
+import { L5xError } from "../core/errors.js";
+import { success } from "../core/result.js";
+import { choice, integer, object, string } from "../core/params.js";
+import { COVERAGE, PROJECT_ID, integerArg, optionalString, requiredString, tool } from "./common.js";
+/** Component kinds the reader can list and open. */
+const KINDS = ['program', 'task', 'tag', 'udt', 'routine', 'aoi', 'module', 'alarm'];
+/**
+ * The offline tools, bound to one chat's project store.
+ *
+ * @param session - Project handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export function readTools(session) {
+    return [
+        tool({
+            name: 'open_project',
+            description: 'Open one Studio 5000 L5X export for this chat. Returns a project_id and a structure summary; every other tool reads this project.',
+            parameters: object({
+                path: string('Path to the .L5X export, absolute or relative to the workspace root. Example: "C:/Projects/Line/Line.L5X"'),
+            }, ['path']),
+            async run(args, exec) {
+                const project = await session.open(requiredString(args, 'path'), exec);
+                const document = project.document;
+                return success(`${document.controller.name}: ${document.programs.length} programs, ${document.tags.length} tags, ${document.routines.length} routines.`, {
+                    project_id: project.id,
+                    path: project.requestedPath,
+                    sha256: project.sha256,
+                    revision: revisionOf(document),
+                    export_revision: project.softwareRevision,
+                    verification: project.verification,
+                    controller: document.controller,
+                    counts: countsOf(document),
+                    programs: document.programs.map(program => ({ name: program.name, mainRoutine: program.mainRoutine })),
+                    tasks: document.tasks.map(task => ({ name: task.name, type: task.type, rate: task.rate, programs: task.programs })),
+                }, [{ tool: 'project_overview', why: 'Confirm tasks, programs and coverage before reading components.' }], COVERAGE);
+            },
+        }),
+        tool({
+            name: 'project_overview',
+            description: 'Structure and coverage of the open project: controller, revision, tasks, programs and component counts.',
+            parameters: object({ project_id: PROJECT_ID }, []),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const document = project.document;
+                return success(`${document.controller.name} (${document.controller.processorType}, revision ${revisionOf(document)}).`, {
+                    project_id: project.id,
+                    controller: document.controller,
+                    revision: revisionOf(document),
+                    export_revision: project.softwareRevision,
+                    verification: project.verification,
+                    counts: countsOf(document),
+                    programs: document.programs,
+                    tasks: document.tasks,
+                }, [
+                    { tool: 'list_components', args: { kind: 'routine' }, why: 'List the routines you can read next.' },
+                    { tool: 'list_components', args: { kind: 'tag' }, why: 'List tags before tracing or reading one.' },
+                ], COVERAGE);
+            },
+        }),
+        tool({
+            name: 'list_components',
+            description: 'List one component kind in the open project, paginated. Use it to find the exact name get_component expects.',
+            parameters: object({
+                kind: choice('Component kind to list.', KINDS),
+                scope: string('Program name for a program-scoped tag or routine. Omit for controller scope.'),
+                filter: string('Case-insensitive substring matched against the component name.'),
+                offset: integer('Zero-based index of the first row to return.', { minimum: 0, default: 0 }),
+                limit: integer('Maximum rows to return.', { minimum: 1, maximum: 200, default: 50 }),
+                project_id: PROJECT_ID,
+            }, ['kind']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const kind = requiredKind(args);
+                const filter = optionalString(args, 'filter') ?? '';
+                const offset = integerArg(args, 'offset', 0);
+                const limit = Math.min(Math.max(integerArg(args, 'limit', 50), 1), 200);
+                const rows = selectRows(project.document, kind, optionalString(args, 'scope'), filter);
+                const page = rows.slice(offset, offset + limit);
+                return success(`${rows.length} ${rows.length === 1 ? kind : `${kind}s`}${filter === '' ? '' : ` matching ${JSON.stringify(filter)}`}.`, { kind, total: rows.length, offset, limit, rows: page }, pageNext(kind, page, offset, limit, rows.length, filter));
+            },
+        }),
+        tool({
+            name: 'get_component',
+            description: 'Read one component in full by exact name: a tag, UDT, routine, AOI, module, program, task or alarm.',
+            parameters: object({
+                kind: choice('Component kind to read.', KINDS),
+                name: string('Exact component name as the export declares it.'),
+                scope: string('Program name when the component is program-scoped.'),
+                project_id: PROJECT_ID,
+            }, ['kind', 'name']),
+            async run(args, exec) {
+                const project = await session.require(optionalString(args, 'project_id'), exec);
+                const kind = requiredKind(args);
+                const name = requiredString(args, 'name');
+                const scope = optionalString(args, 'scope');
+                const component = readComponent(project.document, kind, name, scope);
+                return success(`${kind} ${name}${scope === undefined ? '' : ` in ${scope}`}.`, { kind, component }, [{ tool: 'list_components', args: { kind }, why: 'List the siblings of this component.' }], COVERAGE);
+            },
+        }),
+    ];
+}
+/** A required component kind. */
+function requiredKind(args) {
+    const value = requiredString(args, 'kind');
+    if (!KINDS.includes(value)) {
+        throw new L5xError('INVALID_ARGUMENT', `Unknown component kind ${JSON.stringify(value)}.`, `Pass one of: ${KINDS.join(', ')}.`, KINDS);
+    }
+    return value;
+}
+/** Controller revision as a readable string. */
+function revisionOf(document) {
+    const { majorRev, minorRev } = document.controller;
+    return majorRev === '' ? '' : `${majorRev}.${minorRev}`;
+}
+/** Component counts for a summary. */
+function countsOf(document) {
+    return {
+        programs: document.programs.length,
+        tasks: document.tasks.length,
+        tags: document.tags.length,
+        udts: document.udts.length,
+        routines: document.routines.length,
+        aois: document.aois.length,
+        modules: document.modules.length,
+        alarms: document.alarms.length,
+    };
+}
+/** One kind's rows, filtered and in export order. */
+function selectRows(document, kind, scope, filter) {
+    const rows = kind === 'program'
+        ? document.programs.map(program => ({ name: program.name, mainRoutine: program.mainRoutine, description: program.description }))
+        : kind === 'task'
+            ? document.tasks.map(task => ({ name: task.name, type: task.type, rate: task.rate, programs: task.programs }))
+            : kind === 'tag'
+                ? listTags(document, scope ?? '').map(tag => ({ name: tag.name, scope: tag.scope, dataType: tag.dataType, description: tag.description ?? '', externalAccess: tag.externalAccess ?? '' }))
+                : kind === 'udt'
+                    ? document.udts.map(udt => ({ name: udt.name, members: udt.members.length, description: udt.description }))
+                    : kind === 'routine'
+                        ? listRoutines(document, scope ?? '').map(routine => ({ name: routine.name, program: routine.program, type: routine.type, rungCount: routine.rungCount ?? null, lineCount: routine.lineCount ?? null, description: routine.description }))
+                        : kind === 'aoi'
+                            ? listAois(document).map(aoi => ({ name: aoi.name, revision: aoi.revision, description: aoi.description }))
+                            : kind === 'module'
+                                ? listModules(document).map(module => ({ name: module.name, catalogNumber: module.catalogNumber, slot: module.slot ?? '', parentModule: module.parentModule, inhibited: module.inhibited === true }))
+                                : document.alarms.map(alarm => ({ name: alarm.name, kind: alarm.kind, description: alarm.description }));
+    const needle = filter.toLowerCase();
+    return needle === '' ? rows : rows.filter(row => row.name.toLowerCase().includes(needle));
+}
+/** Next calls for one listing page. */
+function pageNext(kind, page, offset, limit, total, filter) {
+    const next = [];
+    const first = page[0];
+    if (first !== undefined) {
+        const scope = first.scope ?? first.program;
+        next.push({
+            tool: 'get_component',
+            args: scope === undefined ? { kind, name: first.name } : { kind, name: first.name, scope },
+            why: 'Read the first row in full.',
+        });
+    }
+    if (offset + limit < total) {
+        next.push({
+            tool: 'list_components',
+            args: { kind, filter, offset: offset + limit, limit },
+            why: `Read the next ${Math.min(limit, total - offset - limit)} rows.`,
+        });
+    }
+    return next;
+}
+/** One component by exact name, with candidates when the name does not resolve. */
+function readComponent(document, kind, name, scope) {
+    if (kind === 'tag') {
+        const matches = listTags(document, scope ?? '').filter(tag => tag.name === name);
+        const first = matches[0];
+        if (first === undefined)
+            throw notFound(kind, name, listTags(document, scope ?? '').map(tag => tag.name));
+        if (matches.length > 1) {
+            throw new L5xError('AMBIGUOUS_COMPONENT', `${name} is declared in ${matches.length} scopes.`, 'Pass scope to choose one.', matches.map(tag => tag.scope));
+        }
+        return first;
+    }
+    if (kind === 'udt') {
+        const matches = getUdt(document, name);
+        const first = matches[0];
+        if (first === undefined)
+            throw notFound(kind, name, document.udts.map(udt => udt.name));
+        return first;
+    }
+    if (kind === 'routine') {
+        const matches = listRoutines(document, scope ?? '').filter(routine => routine.name === name);
+        const first = matches[0];
+        if (first === undefined)
+            throw notFound(kind, name, listRoutines(document, scope ?? '').map(routine => routine.name));
+        if (matches.length > 1) {
+            throw new L5xError('AMBIGUOUS_COMPONENT', `${name} exists in ${matches.length} programs.`, 'Pass scope with the program name.', matches.map(routine => routine.program));
+        }
+        return getRoutine(document, first.program, name);
+    }
+    if (kind === 'aoi') {
+        const aoi = getAoi(document, name);
+        if (aoi === undefined)
+            throw notFound(kind, name, document.aois.map(entry => entry.name));
+        return aoi;
+    }
+    if (kind === 'module') {
+        const module = document.modules.find(entry => entry.name === name);
+        if (module === undefined)
+            throw notFound(kind, name, document.modules.map(entry => entry.name));
+        return module;
+    }
+    if (kind === 'program') {
+        const program = document.programs.find(entry => entry.name === name);
+        if (program === undefined)
+            throw notFound(kind, name, document.programs.map(entry => entry.name));
+        return program;
+    }
+    if (kind === 'task') {
+        const task = document.tasks.find(entry => entry.name === name);
+        if (task === undefined)
+            throw notFound(kind, name, document.tasks.map(entry => entry.name));
+        return task;
+    }
+    const alarm = document.alarms.find(entry => entry.name === name);
+    if (alarm === undefined)
+        throw notFound(kind, name, document.alarms.map(entry => entry.name));
+    return alarm;
+}
+/** The failure for a name that does not resolve, with near candidates. */
+function notFound(kind, name, names) {
+    const near = names.filter(candidate => candidate.toLowerCase().includes(name.toLowerCase())).slice(0, 5);
+    const candidates = near.length > 0 ? near : names.slice(0, 5);
+    return new L5xError('COMPONENT_NOT_FOUND', `No ${kind} named ${JSON.stringify(name)} in this export.`, candidates.length === 0
+        ? `Call list_components with kind "${kind}" to see what exists.`
+        : `Call list_components with kind "${kind}", or retry with one of the candidates.`, candidates);
+}

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

@@ -0,0 +1,20 @@
+/**
+ * The reference cluster: find logic, follow a symbol, resolve an address, map
+ * one tag's element usage.
+ *
+ * The old surface answered "where is this used" with five tools. This module
+ * answers it with three names that state their intent — `find_references`,
+ * `trace_dependencies`, `resolve_tag` — plus `usage_map` for element/bit
+ * allocation, and `search_logic` for text that is not a symbol.
+ *
+ * @module dsh-engineering-l5x/tools/references
+ */
+import type { ToolDefinition } from '../core/tool.ts';
+import type { ProjectSession } from '../session.ts';
+/**
+ * The reference tools, bound to one chat's project store.
+ *
+ * @param session - Project handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export declare function referenceTools(session: ProjectSession): readonly ToolDefinition[];

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

@@ -0,0 +1,269 @@
+/**
+ * The reference cluster: find logic, follow a symbol, resolve an address, map
+ * one tag's element usage.
+ *
+ * The old surface answered "where is this used" with five tools. This module
+ * answers it with three names that state their intent — `find_references`,
+ * `trace_dependencies`, `resolve_tag` — plus `usage_map` for element/bit
+ * allocation, and `search_logic` for text that is not a symbol.
+ *
+ * @module dsh-engineering-l5x/tools/references
+ */
+import { findReferences } from "../engine/analysis.js";
+import { traceDependencies } from "../engine/project-analysis.js";
+import { resolveTag } from "../engine/tag-resolution.js";
+import { usageMap } from "../engine/usage.js";
+import { L5xError } from "../core/errors.js";
+import { success } from "../core/result.js";
+import { choice, integer, object, string } from "../core/params.js";
+import { COVERAGE, PROJECT_ID, integerArg, optionalString, requiredString, tool } from "./common.js";
+/**
+ * The reference tools, bound to one chat's project store.
+ *
+ * @param session - Project handles for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export function referenceTools(session) {
+    return [
+        tool({
+            name: 'search_logic',
+            description: 'Find literal text in routine logic. Use it to locate a rung, ST line or operand when you do not know the exact symbol name; use find_references when you do.',
+            parameters: object({
+                query: string('Case-insensitive text to find, matched literally inside rung text, ST lines and diagram node labels. Example: "OTE(Motor_Run)".'),
+                limit: integer('Maximum matches to return.', { minimum: 1, maximum: 100, default: 20 }),
+                project_id: PROJECT_ID,
+            }, ['query']),
+            async run(args, exec) {
+                const project = await projectOf(session, args, exec);
+                const query = requiredString(args, 'query');
+                const limit = Math.min(Math.max(integerArg(args, 'limit', 20), 1), 100);
+                const matches = logicMatches(project.document, query);
+                const page = matches.slice(0, limit);
+                const first = page[0];
+                return success(`${matches.length} ${matches.length === 1 ? 'match' : 'matches'} for ${JSON.stringify(query)} in routine logic.`, {
+                    query,
+                    total: matches.length,
+                    returned: page.length,
+                    truncated: matches.length > page.length,
+                    matches: page,
+                }, [
+                    ...(first === undefined || first.program.startsWith('AOI::')
+                        ? []
+                        : [{ tool: 'get_component', args: { kind: 'routine', name: first.routine, scope: first.program }, why: 'Read the routine that contains the first match.' }]),
+                    { tool: 'find_references', args: { symbol: query }, why: 'See every read and write of this name.' },
+                ], COVERAGE);
+            },
+        }),
+        tool({
+            name: 'find_references',
+            description: 'Find where one symbol is read or written in exported logic, with scope, access and confidence. Use trace_dependencies for what feeds a symbol.',
+            parameters: object({
+                symbol: string('Symbol to follow, as declared or as written in logic. Example: "Motor_1" or "Program:MainProgram.Motor_1".'),
+                scope: string('Program scope to search. Omit to search every scope.'),
+                detail: choice('How much evidence to return.', ['summary', 'evidence'], { default: 'summary' }),
+                limit: integer('Maximum evidence rows when detail is "evidence".', { minimum: 1, maximum: 100, default: 20 }),
+                project_id: PROJECT_ID,
+            }, ['symbol']),
+            async run(args, exec) {
+                const project = await projectOf(session, args, exec);
+                const symbol = requiredString(args, 'symbol');
+                const scope = optionalString(args, 'scope');
+                const detail = optionalString(args, 'detail') ?? 'summary';
+                const limit = Math.min(Math.max(integerArg(args, 'limit', 20), 1), 100);
+                const evidence = findReferences(project, symbol, scope);
+                const byAccess = countAccess(evidence);
+                const rows = evidence.slice(0, limit).map(reference => ({
+                    scope: reference.scope,
+                    routine: reference.routine,
+                    ...(reference.rung === undefined ? {} : { rung: reference.rung }),
+                    ...(reference.line === undefined ? {} : { line: reference.line }),
+                    symbol: reference.symbol,
+                    ...(reference.resolved === undefined ? {} : { resolved: reference.resolved }),
+                    access: reference.access,
+                    confidence: reference.confidence,
+                    context: reference.context,
+                }));
+                const first = evidence[0];
+                return success(`${evidence.length} ${evidence.length === 1 ? 'reference' : 'references'} to ${symbol}: ${byAccess.read} read, ${byAccess.write + byAccess.read_write} write, ${byAccess.unknown} unknown.`, {
+                    symbol,
+                    total: evidence.length,
+                    by_access: byAccess,
+                    routines: [...new Set(evidence.map(reference => `${reference.scope}/${reference.routine}`))],
+                    ...(detail === 'evidence' ? { returned: rows.length, truncated: evidence.length > rows.length, evidence: rows } : {}),
+                }, [
+                    { tool: 'trace_dependencies', args: { symbol }, why: 'See what feeds this symbol, not just where it appears.' },
+                    ...(first === undefined
+                        ? []
+                        : [{ tool: 'get_component', args: { kind: 'routine', name: first.routine, scope: first.scope }, why: 'Read the routine holding the first reference.' }]),
+                ], COVERAGE);
+            },
+        }),
+        tool({
+            name: 'trace_dependencies',
+            description: 'Follow what feeds a symbol (upstream) or what it feeds (downstream) through parsed operands. Static evidence only; it does not establish runtime causality.',
+            parameters: object({
+                symbol: string('Symbol to trace. Example: "Conveyor_Run" or "AOI_EncoderScale::Out_FPM".'),
+                scope: string('Program or AOI name that declares the symbol. Omit for controller scope; an AOI::Member symbol resolves against that AOI automatically.'),
+                direction: choice('Which way to follow the graph.', ['upstream', 'downstream'], { default: 'upstream' }),
+                depth: integer('Maximum graph depth to follow. Default 3.', { minimum: 1, maximum: 6, default: 3 }),
+                project_id: PROJECT_ID,
+            }, ['symbol']),
+            async run(args, exec) {
+                const project = await projectOf(session, args, exec);
+                const requested = requiredString(args, 'symbol');
+                const explicitScope = optionalString(args, 'scope');
+                const parts = requested.split('::');
+                const qualified = parts.length > 1 && parts[0] !== '';
+                const scope = explicitScope === undefined
+                    ? (qualified ? normalizeScope(project.document, parts[0]) : 'controller')
+                    : normalizeScope(project.document, explicitScope);
+                const symbol = qualified ? parts.slice(1).join('::') : requested;
+                const direction = optionalString(args, 'direction') === 'downstream' ? 'downstream' : 'upstream';
+                const depth = Math.min(Math.max(integerArg(args, 'depth', 3), 1), 6);
+                const graph = traceDependencies(project, symbol, scope, direction, {
+                    depth,
+                    nodes: 50,
+                    edges: 100,
+                    analysis: { references: 5000, edges: 5000 },
+                });
+                const resolution = graph.resolution;
+                if (resolution !== undefined && resolution.resolved === false) {
+                    const declarations = [...project.document.aois.map(aoi => aoi.name), ...project.document.programs.map(program => program.name)];
+                    throw new L5xError('UNRESOLVED_SYMBOL', `${requested} does not resolve in scope ${scope}: ${resolution.reason ?? 'not declared in this export'}.`, 'Pass scope with the declaring program or AOI. For an AOI member, write "AOI_Name::Member" or pass scope "AOI_Name" with the member name.', declarations.slice(0, 5));
+                }
+                const nodes = graph.nodes;
+                const edges = graph.edges;
+                const coverage = {
+                    complete: graph.static_complete === true,
+                    unverified: [
+                        'runtime causality',
+                        'external HMI, produced/consumed and driver consumers',
+                        'dynamic indices',
+                        ...(graph.truncated === true ? ['the graph was truncated at the configured depth or edge bound'] : []),
+                    ],
+                };
+                return success(`${nodes.length} ${nodes.length === 1 ? 'symbol' : 'symbols'} and ${edges.length} ${edges.length === 1 ? 'edge' : 'edges'} ${direction} of ${requested}${graph.truncated === true ? ' (truncated)' : ''}.`, graph, [
+                    { tool: 'find_references', args: { symbol: requested }, why: 'See every occurrence rather than the dependency graph.' },
+                    ...(requested.includes('::') ? [] : [{ tool: 'usage_map', args: { tag: requested, scope }, why: 'Map element and bit usage for this tag.' }]),
+                ], coverage);
+            },
+        }),
+        tool({
+            name: 'resolve_tag',
+            description: 'Resolve one Logix address against exported declarations: alias chain, member, integer bit and array subscript, with the evidence that remains unverified.',
+            parameters: object({
+                address: string('Address as written in logic. Example: "Motor_1.Speed" or "Alarms[2].3".'),
+                scope: string('Program scope for a local tag. Omit for controller scope.'),
+                project_id: PROJECT_ID,
+            }, ['address']),
+            async run(args, exec) {
+                const project = await projectOf(session, args, exec);
+                const address = requiredString(args, 'address');
+                const resolution = resolveTag(project.document, optionalString(args, 'scope') ?? 'controller', address);
+                const canonical = resolution.canonical;
+                return success(resolution.resolved
+                    ? `${address} resolves to ${canonical ?? 'its declared type'}${resolution.data_type === undefined ? '' : ` (${resolution.data_type})`}.`
+                    : `${address} does not resolve: ${resolution.reason ?? 'not declared in this export'}.`, resolution, [
+                    { tool: 'find_references', args: { symbol: address }, why: 'See where this address is used.' },
+                    ...(canonical === undefined
+                        ? []
+                        : [{ tool: 'find_references', args: { symbol: canonical.split(/[.[]/u)[0] ?? canonical }, why: 'Follow the base declaration this address resolves to.' }]),
+                ], resolution.indices_verified
+                    ? COVERAGE
+                    : { complete: false, unverified: ['a dynamic subscript was not expanded', ...COVERAGE.unverified] });
+            },
+        }),
+        tool({
+            name: 'usage_map',
+            description: 'Map how one declared tag is used: which array elements and bits are read or written, which remain free, and where each appears.',
+            parameters: object({
+                tag: string('Declared tag name. Example: "Alarm_Bits".'),
+                scope: string('Declaring scope: "controller" or a program name. Defaults to controller.'),
+                project_id: PROJECT_ID,
+            }, ['tag']),
+            async run(args, exec) {
+                const project = await projectOf(session, args, exec);
+                const tag = requiredString(args, 'tag');
+                const scope = optionalString(args, 'scope') ?? 'controller';
+                const declared = project.document.tags.find(entry => entry.name.toLowerCase() === tag.toLowerCase() && entry.scope.toLowerCase() === scope.toLowerCase());
+                if (declared === undefined) {
+                    const declaredHere = project.document.tags
+                        .filter(entry => entry.scope.toLowerCase() === scope.toLowerCase())
+                        .map(entry => entry.name);
+                    throw new L5xError('COMPONENT_NOT_FOUND', `Tag ${JSON.stringify(tag)} is not declared in scope ${JSON.stringify(scope)}.`, 'Call list_components with kind "tag" to see the declared names in this scope.', declaredHere.slice(0, 5));
+                }
+                const map = usageMap(project, scope, tag);
+                const indexes = map.indexes ?? [];
+                return success(`${declared.name}: ${indexes.length} indexed ${indexes.length === 1 ? 'element' : 'elements'} used${map.whole_element ? ', plus whole-tag use' : ''}.`, map, [{ tool: 'find_references', args: { symbol: declared.name, scope }, why: 'See every occurrence behind these counts.' }], {
+                    complete: false,
+                    unverified: ['external HMI, produced/consumed and driver consumers', 'dynamic indices are not expanded'],
+                });
+            },
+        }),
+    ];
+}
+/** Resolve the calling project. */
+async function projectOf(session, args, exec) {
+    return await session.require(optionalString(args, 'project_id'), exec);
+}
+/** The declaration scope a symbol resolves against: an AOI name becomes `AOI::Name`. */
+function normalizeScope(document, scope) {
+    if (scope.startsWith('AOI::'))
+        return scope;
+    return document.aois.some(aoi => aoi.name === scope) ? `AOI::${scope}` : scope;
+}
+/** Count evidence by access kind. */
+function countAccess(evidence) {
+    const counts = { read: 0, write: 0, read_write: 0, call: 0, unknown: 0 };
+    for (const entry of evidence) {
+        if (entry.access === 'read')
+            counts.read += 1;
+        else if (entry.access === 'write')
+            counts.write += 1;
+        else if (entry.access === 'read_write')
+            counts.read_write += 1;
+        else if (entry.access === 'call')
+            counts.call += 1;
+        else
+            counts.unknown += 1;
+    }
+    return counts;
+}
+/** Literal, case-insensitive matches across routine logic. */
+function logicMatches(document, query) {
+    const needle = query.toLowerCase();
+    const matches = [];
+    const routines = [...document.routines, ...document.aois.flatMap(aoi => aoi.routines.map(routine => ({ ...routine, program: `AOI::${aoi.name}` })))];
+    for (const routine of routines) {
+        if (routine.body.type === 'RLL') {
+            for (const rung of routine.body.rungs) {
+                if (!rung.text.toLowerCase().includes(needle))
+                    continue;
+                matches.push({
+                    program: routine.program,
+                    routine: routine.name,
+                    language: 'RLL',
+                    rung: rung.number,
+                    text: rung.text,
+                    ...(rung.comment === undefined ? {} : { comment: rung.comment }),
+                });
+            }
+        }
+        else if (routine.body.type === 'ST') {
+            routine.body.code.split(/\r?\n/u).forEach((line, index) => {
+                if (line.toLowerCase().includes(needle)) {
+                    matches.push({ program: routine.program, routine: routine.name, language: 'ST', line: index + 1, text: line.trim() });
+                }
+            });
+        }
+        else if (routine.body.type === 'FBD' || routine.body.type === 'SFC') {
+            for (const node of routine.body.nodes) {
+                const text = node.text ?? node.operand ?? '';
+                if (text.toLowerCase().includes(needle)) {
+                    matches.push({ program: routine.program, routine: routine.name, language: routine.body.type, sheet: node.sheet, text });
+                }
+            }
+        }
+    }
+    return matches;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * The online-supervised entry's offline half: SDK status, ACD export, L5X
+ * verification, routine build into a new ACD, and review-evidence checking.
+ *
+ * No tool here contacts a controller. Upload, mode change and download belong
+ * to the controller tools, which require per-call human approval and are not
+ * part of this entry yet.
+ *
+ * @module dsh-engineering-l5x/tools/studio
+ */
+import type { ToolDefinition } from '../core/tool.ts';
+import type { ProjectSession } from '../session.ts';
+import type { StudioState } from '../studio-state.ts';
+/**
+ * The studio tools, bound to one chat's projects and export provenance.
+ *
+ * @param session - Project handles for the calling chat.
+ * @param state - ACD export records for the calling chat.
+ * @returns Tool definitions in registration order.
+ */
+export declare function studioTools(session: ProjectSession, state: StudioState): readonly ToolDefinition[];