sf-agentpmd 0.1.0

package/dist/analyzer/analyze.js

@@ -0,0 +1,222 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { collectDeclarations, collectReferences } from './action-references.js';
+import { analyzeReferencedApex } from './apex-analyze.js';
+import { collectScopes, complexityForFile } from './complexity.js';
+import { extractDeveloperName, parseAgentSource } from './parse.js';
+/**
+ * Error thrown when --api-name filters produce no matches. Carries the
+ * candidate list so callers can show a useful hint.
+ */
+export class NoMatchingBundlesError extends Error {
+    requested;
+    available;
+    constructor(requested, available) {
+        super(`No agent bundle matched ${requested.map(n => `'${n}'`).join(', ')}. ` +
+            `Available: ${available.map((b) => formatBundleIdentity(b)).join(', ')}`);
+        this.requested = requested;
+        this.available = available;
+        this.name = 'NoMatchingBundlesError';
+    }
+}
+function formatBundleIdentity(b) {
+    if (b.developerName && b.developerName !== b.dirName) {
+        return `${b.developerName} (dir: ${b.dirName})`;
+    }
+    return b.dirName;
+}
+/**
+ * Analyze AgentScript bundles under one or more source roots.
+ *
+ * Backward-compatible: pass a single path (string) for the legacy
+ * single-root case. Pass an array of paths for multi-root analysis
+ * (e.g. multiple `packageDirectories` in an sfdx project).
+ */
+export async function analyzeSource(rootPathOrPaths, options = {}) {
+    const rawRoots = Array.isArray(rootPathOrPaths)
+        ? rootPathOrPaths
+        : [rootPathOrPaths];
+    if (rawRoots.length === 0) {
+        throw new Error('analyzeSource requires at least one source path');
+    }
+    const absRoots = rawRoots.map(p => resolve(p));
+    const reportBase = options.reportBase
+        ? resolve(options.reportBase)
+        : absRoots.length === 1
+            ? absRoots[0]
+            : longestCommonAncestor(absRoots);
+    const allFiles = [];
+    for (const root of absRoots) {
+        const files = await findAgentFiles(root);
+        for (const f of files)
+            if (!allFiles.includes(f))
+                allFiles.push(f);
+    }
+    allFiles.sort();
+    const filteredFiles = await filterByApiNames(allFiles, options.apiNames);
+    const fileReports = [];
+    for (const file of filteredFiles) {
+        fileReports.push(await analyzeFile(file, reportBase));
+    }
+    const apex = await analyzeReferencedApex({
+        agentAbsPaths: filteredFiles,
+        apexSourceOverride: options.apexSourceOverride,
+        fileReports,
+        sourceDirRoot: reportBase,
+    });
+    const report = {
+        apexClasses: apex.classes,
+        byTargetKind: tallyTargets(fileReports),
+        files: fileReports,
+        totalApexComplexity: apex.classes.reduce((acc, c) => acc + c.classComplexity, 0),
+        totalComplexity: fileReports.reduce((acc, f) => acc + f.fileComplexity, 0),
+        totalDeclarations: fileReports.reduce((acc, f) => acc + f.declarations.length, 0),
+        totalReferences: fileReports.reduce((acc, f) => acc + f.references.length, 0),
+        unresolvedApexTargets: apex.unresolved,
+    };
+    return report;
+}
+export async function analyzeFile(absPath, base) {
+    const source = await readFile(absPath, 'utf8');
+    const root = parseAgentSource(source);
+    const cc = complexityForFile(root);
+    const { procedures } = cc;
+    const scopes = collectScopes(root);
+    const declarations = [];
+    const references = [];
+    for (const s of scopes) {
+        declarations.push(...collectDeclarations(s));
+        references.push(...collectReferences(s));
+    }
+    return {
+        declarations,
+        fileComplexity: cc.total,
+        parseErrors: [], // CST is error-tolerant; surface diagnostics in a later iteration.
+        path: relative(base, absPath),
+        procedures,
+        references,
+    };
+}
+async function findAgentFiles(root) {
+    const s = await stat(root).catch(() => { });
+    if (!s)
+        throw new Error(`source path does not exist: ${root}`);
+    if (s.isFile())
+        return root.endsWith('.agent') ? [root] : [];
+    const out = [];
+    const visit = async (dir) => {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const e of entries) {
+            if (e.name.startsWith('.'))
+                continue;
+            if (e.name === 'node_modules' || e.name === 'vendor' || e.name === 'lib')
+                continue;
+            const full = join(dir, e.name);
+            if (e.isDirectory())
+                await visit(full);
+            else if (e.isFile() && e.name.endsWith('.agent'))
+                out.push(full);
+        }
+    };
+    await visit(root);
+    out.sort();
+    return out;
+}
+function tallyTargets(files) {
+    const acc = {
+        apex: 0,
+        flow: 0,
+        prompt: 0,
+        unknown: 0,
+        utils: 0,
+    };
+    for (const f of files)
+        for (const d of f.declarations)
+            acc[d.targetKind]++;
+    return acc;
+}
+/**
+ * Filter the discovered .agent file list by the supplied `--api-name`
+ * values. A bundle matches if (a) its directory name equals a requested
+ * name, or (b) its `config.developer_name` equals one. Bundles whose dir
+ * name already matches are kept without parsing; only the remainder are
+ * parsed for `developer_name` resolution.
+ *
+ * Throws NoMatchingBundlesError when filters were supplied but nothing
+ * matched, so callers can show the available list.
+ */
+async function filterByApiNames(files, apiNames) {
+    if (!apiNames || apiNames.length === 0)
+        return files;
+    const wanted = new Set(apiNames);
+    const matches = [];
+    const unmatched = [];
+    for (const file of files) {
+        const dirName = basename(dirname(file));
+        if (wanted.has(dirName)) {
+            matches.push(file);
+        }
+        else {
+            unmatched.push(file);
+        }
+    }
+    if (matches.length === files.length || unmatched.length === 0) {
+        return matches;
+    }
+    // Slow path: parse the still-unmatched files to read developer_name.
+    const identities = [];
+    for (const file of unmatched) {
+        const dirName = basename(dirname(file));
+        const developerName = await readDeveloperName(file);
+        identities.push({ developerName, dirName, path: file });
+        if (developerName && wanted.has(developerName)) {
+            matches.push(file);
+        }
+    }
+    if (matches.length === 0) {
+        // Build the full candidate list (matched dirs + parsed unmatched) for
+        // the error message.
+        const all = [];
+        for (const file of files) {
+            const existing = identities.find(i => i.path === file);
+            if (existing) {
+                all.push(existing);
+            }
+            else {
+                all.push({
+                    developerName: await readDeveloperName(file),
+                    dirName: basename(dirname(file)),
+                    path: file,
+                });
+            }
+        }
+        all.sort((a, b) => a.dirName.localeCompare(b.dirName));
+        throw new NoMatchingBundlesError(apiNames, all);
+    }
+    matches.sort();
+    return matches;
+}
+async function readDeveloperName(file) {
+    const source = await readFile(file, 'utf8');
+    const root = parseAgentSource(source);
+    return extractDeveloperName(root);
+}
+function longestCommonAncestor(paths) {
+    if (paths.length === 0)
+        return process.cwd();
+    if (paths.length === 1)
+        return paths[0];
+    const split = paths.map(p => p.split('/'));
+    const minLen = Math.min(...split.map(s => s.length));
+    const common = [];
+    for (let i = 0; i < minLen; i++) {
+        const seg = split[0][i];
+        if (split.every(s => s[i] === seg))
+            common.push(seg);
+        else
+            break;
+    }
+    const joined = common.join('/') || '/';
+    return joined;
+}
+//# sourceMappingURL=analyze.js.map

package/dist/analyzer/analyze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../../src/analyzer/analyze.ts"],"names":[],"mappings":"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"}

package/dist/analyzer/apex-analyze.d.ts

@@ -0,0 +1,14 @@
+import type { ApexClassReport, FileReport } from './types.js';
+/** Inputs needed to resolve and analyze every apex:// target in the bundle. */
+export interface ApexAnalyzeInputs {
+    /** Absolute paths of every .agent file analyzed, parallel to fileReports. */
+    agentAbsPaths: string[];
+    apexSourceOverride?: string;
+    fileReports: FileReport[];
+    sourceDirRoot: string;
+}
+export interface ApexAnalyzeOutputs {
+    classes: ApexClassReport[];
+    unresolved: string[];
+}
+export declare function analyzeReferencedApex(inputs: ApexAnalyzeInputs): Promise<ApexAnalyzeOutputs>;

package/dist/analyzer/apex-analyze.js

@@ -0,0 +1,60 @@
+import { readFile } from 'node:fs/promises';
+import { basename, relative } from 'node:path';
+import { complexityOfMethod, methodsInCompilationUnit } from './apex-complexity.js';
+import { parseApexSource } from './apex-parse.js';
+import { extractApexClassName, resolveApexClassPath, } from './apex-resolve.js';
+export async function analyzeReferencedApex(inputs) {
+    const byPath = new Map();
+    const unresolved = new Set();
+    for (let i = 0; i < inputs.fileReports.length; i++) {
+        const fr = inputs.fileReports[i];
+        const agentAbs = inputs.agentAbsPaths[i];
+        for (const decl of fr.declarations) {
+            if (decl.targetKind !== 'apex' || !decl.target)
+                continue;
+            const className = extractApexClassName(decl.target);
+            if (!className) {
+                unresolved.add(decl.target);
+                continue;
+            }
+            const path = await resolveApexClassPath(className, {
+                agentFilePath: agentAbs,
+                apexSourceOverride: inputs.apexSourceOverride,
+                sourceDirRoot: inputs.sourceDirRoot,
+            });
+            if (!path) {
+                unresolved.add(decl.target);
+                continue;
+            }
+            const existing = byPath.get(path);
+            if (existing) {
+                if (!existing.referencedBy.includes(fr.path)) {
+                    existing.referencedBy.push(fr.path);
+                }
+                continue;
+            }
+            const report = await analyzeApexClass(path, className, [fr.path], inputs.sourceDirRoot);
+            byPath.set(path, report);
+        }
+    }
+    return {
+        classes: [...byPath.values()].sort((a, b) => a.className.localeCompare(b.className)),
+        unresolved: [...unresolved].sort(),
+    };
+}
+async function analyzeApexClass(absPath, className, referencedBy, sourceDirRoot) {
+    const source = await readFile(absPath, 'utf8');
+    const cu = parseApexSource(source);
+    const methodCtxs = methodsInCompilationUnit(cu);
+    const methods = methodCtxs.map((m) => complexityOfMethod(m));
+    const classComplexity = methods.reduce((acc, m) => acc + m.complexity, 0);
+    return {
+        classComplexity,
+        className: className || basename(absPath, '.cls'),
+        methods,
+        parseErrors: [],
+        path: relative(sourceDirRoot, absPath),
+        referencedBy,
+    };
+}
+//# sourceMappingURL=apex-analyze.js.map

package/dist/analyzer/apex-analyze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apex-analyze.js","sourceRoot":"","sources":["../../src/analyzer/apex-analyze.ts"],"names":[],"mappings":"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"}

package/dist/analyzer/apex-complexity.d.ts

@@ -0,0 +1,27 @@
+import { type CompilationUnitContext, ConstructorDeclarationContext, MethodDeclarationContext } from '@apexdevtools/apex-parser';
+import type { ApexMethodCC } from './types.js';
+/**
+ * Standard McCabe Cyclomatic Complexity for Apex, per the SonarQube /
+ * PMD CyclomaticComplexity convention used in the categorization
+ * whitepaper § 7:
+ *
+ *   CC = 1
+ *      + count(if)
+ *      + count(for)        // includes enhanced-for (for-each)
+ *      + count(while)
+ *      + count(do-while)
+ *      + count(when arm)   // each switch `when X { ... }`; `when else` excluded
+ *      + count(catch)      // each catch clause
+ *      + count(ternary ?:)
+ *      + count(&&)
+ *      + count(||)
+ *
+ * Not counted: else, when else, finally, try itself.
+ */
+export declare function complexityOfMethod(methodCtx: ConstructorDeclarationContext | MethodDeclarationContext): ApexMethodCC;
+/**
+ * Enumerate every method and constructor in a compilation unit, including
+ * those nested inside inner classes. Each gets its own CC entry per the
+ * v2 scope ("all methods in any class touched by apex://").
+ */
+export declare function methodsInCompilationUnit(cu: CompilationUnitContext): Array<ConstructorDeclarationContext | MethodDeclarationContext>;

package/dist/analyzer/apex-complexity.js

@@ -0,0 +1,133 @@
+import { CatchClauseContext, CondExpressionContext, ConstructorDeclarationContext, DoWhileStatementContext, ForStatementContext, IfStatementContext, LogAndExpressionContext, LogOrExpressionContext, MethodDeclarationContext, WhenControlContext, WhileStatementContext, } from '@apexdevtools/apex-parser';
+import { locOfCtx, walkParseTree } from './apex-parse.js';
+/**
+ * Standard McCabe Cyclomatic Complexity for Apex, per the SonarQube /
+ * PMD CyclomaticComplexity convention used in the categorization
+ * whitepaper § 7:
+ *
+ *   CC = 1
+ *      + count(if)
+ *      + count(for)        // includes enhanced-for (for-each)
+ *      + count(while)
+ *      + count(do-while)
+ *      + count(when arm)   // each switch `when X { ... }`; `when else` excluded
+ *      + count(catch)      // each catch clause
+ *      + count(ternary ?:)
+ *      + count(&&)
+ *      + count(||)
+ *
+ * Not counted: else, when else, finally, try itself.
+ */
+export function complexityOfMethod(methodCtx) {
+    const body = methodCtx.block();
+    const contributors = [];
+    if (body) {
+        walkParseTree(body, node => {
+            // Don't descend into nested methods/constructors — they have their
+            // own CC counted separately.
+            if (node !== methodCtx &&
+                (node instanceof MethodDeclarationContext ||
+                    node instanceof ConstructorDeclarationContext)) {
+                // walkParseTree will still recurse into this node's subtree.
+                // We can't easily prune, so we filter by parentage: skip
+                // contributors whose nearest enclosing method/ctor is not us.
+                return;
+            }
+            const kind = classifyContributor(node);
+            if (kind !== undefined && enclosingMethod(node) === methodCtx) {
+                contributors.push({ kind, location: locOfCtx(node) });
+            }
+        });
+    }
+    const name = methodCtx instanceof ConstructorDeclarationContext
+        ? methodCtx.qualifiedName()?.getText() ?? '<ctor>'
+        : methodCtx.id()?.getText() ?? '<anon>';
+    const signature = renderSignature(methodCtx, name);
+    return {
+        complexity: 1 + contributors.length,
+        contributors,
+        kind: methodCtx instanceof ConstructorDeclarationContext ? 'constructor' : 'method',
+        location: locOfCtx(methodCtx),
+        name,
+        signature,
+    };
+}
+function classifyContributor(node) {
+    if (node instanceof IfStatementContext)
+        return 'if_statement';
+    if (node instanceof ForStatementContext)
+        return 'for_statement';
+    if (node instanceof WhileStatementContext)
+        return 'while_statement';
+    if (node instanceof DoWhileStatementContext)
+        return 'do_while_statement';
+    if (node instanceof WhenControlContext) {
+        // `when else { ... }` is the default arm → don't count it.
+        const wv = node.whenValue();
+        const elseTok = wv && typeof wv.ELSE === 'function' ? wv.ELSE() : undefined;
+        return elseTok ? undefined : 'when_arm';
+    }
+    if (node instanceof CatchClauseContext)
+        return 'catch_clause';
+    if (node instanceof CondExpressionContext)
+        return 'ternary';
+    if (node instanceof LogAndExpressionContext)
+        return 'short_circuit_and';
+    if (node instanceof LogOrExpressionContext)
+        return 'short_circuit_or';
+    return undefined;
+}
+function enclosingMethod(node) {
+    let p = node.parentCtx;
+    while (p) {
+        if (p instanceof MethodDeclarationContext || p instanceof ConstructorDeclarationContext) {
+            return p;
+        }
+        p = p.parentCtx;
+    }
+    return undefined;
+}
+function renderSignature(ctx, name) {
+    const paramsText = renderFormalParameters(ctx.formalParameters());
+    if (ctx instanceof MethodDeclarationContext) {
+        const retType = ctx.typeRef()?.getText() ?? (ctx.VOID() ? 'void' : '');
+        return `${retType ? retType + ' ' : ''}${name}${paramsText}`;
+    }
+    return `${name}${paramsText}`;
+}
+/**
+ * ANTLR's `getText()` concatenates child tokens with no whitespace, which
+ * mangles parameter lists like `List<Request> requests` into
+ * `List<Request>requests`. Walk the structured children and rebuild a
+ * properly-spaced signature.
+ */
+function renderFormalParameters(params) {
+    if (!params)
+        return '()';
+    const list = params.formalParameterList();
+    if (!list)
+        return '()';
+    const parts = list.formalParameter_list().map(p => {
+        const type = p.typeRef()?.getText() ?? '';
+        const id = p.id()?.getText() ?? '';
+        return type && id ? `${type} ${id}` : type || id;
+    });
+    return `(${parts.join(', ')})`;
+}
+/**
+ * Enumerate every method and constructor in a compilation unit, including
+ * those nested inside inner classes. Each gets its own CC entry per the
+ * v2 scope ("all methods in any class touched by apex://").
+ */
+export function methodsInCompilationUnit(cu) {
+    const out = [];
+    walkParseTree(cu, node => {
+        if ((node instanceof MethodDeclarationContext ||
+            node instanceof ConstructorDeclarationContext) &&
+            node.block()) {
+            out.push(node);
+        }
+    });
+    return out;
+}
+//# sourceMappingURL=apex-complexity.js.map

package/dist/analyzer/apex-complexity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apex-complexity.js","sourceRoot":"","sources":["../../src/analyzer/apex-complexity.ts"],"names":[],"mappings":"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"}

package/dist/analyzer/apex-parse.d.ts

@@ -0,0 +1,39 @@
+import { CompilationUnitContext } from '@apexdevtools/apex-parser';
+/**
+ * Structural view of an ANTLR parse-tree node covering only the members this
+ * analyzer touches. `@apexdevtools/apex-parser` 5.x ships generated context
+ * types that extend antlr4's `ParserRuleContext`, but antlr4 4.13.x does not
+ * surface `ParserRuleContext` (nor its inherited `getText`/`getChild`) through
+ * its NodeNext `.d.cts` re-export chain, so importing it directly fails to
+ * resolve. We model the contract locally instead — the runtime objects carry
+ * all of these methods.
+ */
+export interface ApexRuleNode {
+    getChild(i: number): unknown;
+    getChildCount(): number;
+    getText(): string;
+    parentCtx?: ApexRuleNode | undefined;
+    start?: {
+        column?: number;
+        line?: number;
+        text?: string;
+    };
+    stop?: {
+        column?: number;
+        line?: number;
+        text?: string;
+    };
+}
+export declare function parseApexSource(source: string): CompilationUnitContext;
+export declare function locOfCtx(ctx: ApexRuleNode): {
+    endCol: number;
+    endRow: number;
+    startCol: number;
+    startRow: number;
+};
+/**
+ * Walk an ANTLR parse-tree node depth-first, invoking the visitor on every
+ * descendant (including the start node). Terminal/error nodes have no
+ * children and are visited like any other node — caller filters by type.
+ */
+export declare function walkParseTree(node: ApexRuleNode, visit: (n: ApexRuleNode) => void): void;

package/dist/analyzer/apex-parse.js

@@ -0,0 +1,32 @@
+import { ApexParserFactory, } from '@apexdevtools/apex-parser';
+export function parseApexSource(source) {
+    const parser = ApexParserFactory.createParser(source);
+    return parser.compilationUnit();
+}
+export function locOfCtx(ctx) {
+    const { start } = ctx;
+    const stop = ctx.stop ?? ctx.start;
+    return {
+        endCol: (stop?.column ?? 0) + (stop?.text?.length ?? 0),
+        endRow: stop?.line ?? 0,
+        startCol: start?.column ?? 0,
+        startRow: start?.line ?? 0,
+    };
+}
+/**
+ * Walk an ANTLR parse-tree node depth-first, invoking the visitor on every
+ * descendant (including the start node). Terminal/error nodes have no
+ * children and are visited like any other node — caller filters by type.
+ */
+export function walkParseTree(node, visit) {
+    visit(node);
+    const childCount = typeof node.getChildCount === 'function' ? node.getChildCount() : 0;
+    for (let i = 0; i < childCount; i++) {
+        const c = node.getChild(i);
+        // Filter to ParserRuleContext children only — terminals don't carry rules.
+        if (c && typeof c.getChildCount === 'function') {
+            walkParseTree(c, visit);
+        }
+    }
+}
+//# sourceMappingURL=apex-parse.js.map

package/dist/analyzer/apex-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apex-parse.js","sourceRoot":"","sources":["../../src/analyzer/apex-parse.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,GAElB,MAAM,2BAA2B,CAAC;AAoBnC,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,MAAM,GAAG,iBAAiB,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC,eAAe,EAAE,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAiB;IACxC,MAAM,EAAC,KAAK,EAAC,GAAG,GAAG,CAAC;IACpB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC;IACnC,OAAO;QACL,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC;QACvD,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;QACvB,QAAQ,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC;QAC5B,QAAQ,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC;KAC3B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAkB,EAClB,KAAgC;IAEhC,KAAK,CAAC,IAAI,CAAC,CAAC;IACZ,MAAM,UAAU,GACd,OAAO,IAAI,CAAC,aAAa,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC3B,2EAA2E;QAC3E,IAAI,CAAC,IAAI,OAAQ,CAAkB,CAAC,aAAa,KAAK,UAAU,EAAE,CAAC;YACjE,aAAa,CAAC,CAAiB,EAAE,KAAK,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/analyzer/apex-resolve.d.ts

@@ -0,0 +1,32 @@
+export declare function extractApexClassName(uri: string): string | undefined;
+export interface ResolveOptions {
+    /**
+     * The .agent file that holds the apex:// reference. Used as the seed for
+     * the upward walk.
+     */
+    agentFilePath: string;
+    /**
+     * Optional `--apex-source` override. When set, classes are looked up here
+     * before falling back to the upward walk.
+     */
+    apexSourceOverride?: string;
+    /**
+     * The CLI `--source-dir` value. We never walk above this directory.
+     */
+    sourceDirRoot: string;
+}
+/**
+ * Find `classes/<ClassName>.cls` by walking up from the .agent file. The walk
+ * stops at the CLI's source-dir root so we never escape it. Returns the
+ * absolute path or undefined.
+ *
+ * Path conventions covered:
+ *   - sfdx default: <pkg>/main/default/classes/<X>.cls, with the .agent in
+ *     <pkg>/main/default/aiAuthoringBundles/<Bundle>/<X>.agent
+ *   - flat fixtures: <root>/classes/<X>.cls, with .agent under
+ *     <root>/aiAuthoringBundles/<Bundle>/<X>.agent
+ *   - explicit override: --apex-source <dir>/<X>.cls
+ */
+export declare function resolveApexClassPath(className: string, opts: ResolveOptions): Promise<string | undefined>;
+/** True if `child` is the same as or a subpath of `parent` (path-segment safe). */
+export declare function isUnder(child: string, parent: string): boolean;

package/dist/analyzer/apex-resolve.js

@@ -0,0 +1,59 @@
+import { stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+const APEX_SCHEME = /^apex:\/\/(.+)$/;
+export function extractApexClassName(uri) {
+    const m = APEX_SCHEME.exec(uri);
+    if (!m)
+        return undefined;
+    // `apex://Foo` or `apex://namespace__Foo`; take the trailing simple name.
+    const raw = m[1].trim();
+    const dot = raw.lastIndexOf('.');
+    return dot === -1 ? raw : raw.slice(dot + 1);
+}
+/**
+ * Find `classes/<ClassName>.cls` by walking up from the .agent file. The walk
+ * stops at the CLI's source-dir root so we never escape it. Returns the
+ * absolute path or undefined.
+ *
+ * Path conventions covered:
+ *   - sfdx default: <pkg>/main/default/classes/<X>.cls, with the .agent in
+ *     <pkg>/main/default/aiAuthoringBundles/<Bundle>/<X>.agent
+ *   - flat fixtures: <root>/classes/<X>.cls, with .agent under
+ *     <root>/aiAuthoringBundles/<Bundle>/<X>.agent
+ *   - explicit override: --apex-source <dir>/<X>.cls
+ */
+export async function resolveApexClassPath(className, opts) {
+    const candidates = [];
+    if (opts.apexSourceOverride) {
+        const override = isAbsolute(opts.apexSourceOverride)
+            ? opts.apexSourceOverride
+            : resolve(opts.apexSourceOverride);
+        candidates.push(join(override, `${className}.cls`), join(override, 'classes', `${className}.cls`));
+    }
+    const stop = resolve(opts.sourceDirRoot);
+    let dir = dirname(resolve(opts.agentFilePath));
+    while (true) {
+        candidates.push(join(dir, 'classes', `${className}.cls`));
+        if (dir === stop)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    for (const c of candidates) {
+        const s = await stat(c).catch(() => { });
+        if (s?.isFile())
+            return c;
+    }
+    return undefined;
+}
+/** True if `child` is the same as or a subpath of `parent` (path-segment safe). */
+export function isUnder(child, parent) {
+    const c = resolve(child);
+    const p = resolve(parent);
+    if (c === p)
+        return true;
+    return c.startsWith(p.endsWith(sep) ? p : p + sep);
+}
+//# sourceMappingURL=apex-resolve.js.map