@simplysf/simply-apex 1.6.8 → 1.6.10

package/lib/common/apexTraceSetup.js

@@ -0,0 +1,142 @@
+/*
+ * Copyright (c) 2026, Clay Chipps.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { escapeSoqlLiteral } from '@simplysf/simply-core';
+/** DeveloperName used for the FINEST/FINER debug level created for the Apex Replay Debugger. */
+const DEBUG_LEVEL_NAME = 'ReplayDebuggerLevels';
+/** How long a configured trace flag stays active before expiring, in milliseconds (24 hours). */
+const TRACE_DURATION_MS = 24 * 60 * 60 * 1000;
+/** Matches the ISO 8601 date-time format `--start-date`/`--end-date` require. */
+export const DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+/**
+ * Matches `Field:Value` for `--on-behalf-of`. The field name is restricted to safe SOQL identifier
+ * characters since, unlike the value, it can't be quoted/escaped in the query.
+ */
+export const ON_BEHALF_OF_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*):(.+)$/;
+/** @returns `input` parsed as a `Field:Value` pair, or `undefined` if it doesn't match `ON_BEHALF_OF_PATTERN`. */
+export function parseOnBehalfOf(input) {
+    const match = ON_BEHALF_OF_PATTERN.exec(input);
+    if (!match) {
+        return undefined;
+    }
+    const [, field, value] = match;
+    return { field, value };
+}
+export class ApexTraceSetupError extends Error {
+    code;
+    /** The raw values a `Messages`-based caller needs to reproduce its own error text (e.g. `[userIdentifier]`, `[expirationDate, startDate]`) — not necessarily the same as `message`, which is this error's own human-readable text. */
+    args;
+    constructor(code, message, args = [message]) {
+        super(message);
+        this.name = 'ApexTraceSetupError';
+        this.code = code;
+        this.args = args;
+    }
+}
+/** @returns The Id of the single user matching `onBehalfOf` (or `connection`'s own username if `onBehalfOf` is absent). @throws {ApexTraceSetupError} `user-not-found`/`ambiguous-on-behalf-of`. */
+async function findTraceTargetUserId(connection, onBehalfOf) {
+    const userFilterField = onBehalfOf?.field ?? 'Username';
+    const userFilterValue = onBehalfOf?.value ?? connection.getUsername() ?? '';
+    const userIdentifier = onBehalfOf ? `${onBehalfOf.field}:${onBehalfOf.value}` : userFilterValue;
+    const userQueryResult = await connection.query(`SELECT Id FROM User WHERE ${userFilterField} = '${escapeSoqlLiteral(userFilterValue)}' LIMIT 2`);
+    if (userQueryResult.records.length === 0) {
+        throw new ApexTraceSetupError('user-not-found', `No user found matching "${userIdentifier}".`, [userIdentifier]);
+    }
+    if (userQueryResult.records.length > 1) {
+        throw new ApexTraceSetupError('ambiguous-on-behalf-of', `More than one user matches "${userIdentifier}".`, [
+            userIdentifier,
+        ]);
+    }
+    return userQueryResult.records[0].Id;
+}
+/** @returns The Id of `requestedLogLevel` if given (must already exist), or the shared `ReplayDebuggerLevels` debug level's Id (created if absent). @throws {ApexTraceSetupError} `debug-level-not-found`/`debug-level-create-failed`. */
+async function findOrCreateDebugLevel(connection, requestedLogLevel) {
+    const debugLevelName = requestedLogLevel ?? DEBUG_LEVEL_NAME;
+    const debugLevelResult = await connection.tooling.query(`SELECT Id FROM DebugLevel WHERE DeveloperName = '${debugLevelName}'`);
+    if (debugLevelResult.records.length > 0) {
+        return debugLevelResult.records[0].Id;
+    }
+    if (requestedLogLevel) {
+        throw new ApexTraceSetupError('debug-level-not-found', `No DebugLevel named "${debugLevelName}" was found.`, [
+            debugLevelName,
+        ]);
+    }
+    const createResult = await connection.tooling.sobject('DebugLevel').create({
+        DeveloperName: DEBUG_LEVEL_NAME,
+        MasterLabel: DEBUG_LEVEL_NAME,
+        ApexCode: 'FINEST',
+        Visualforce: 'FINER',
+    });
+    if (!createResult.success) {
+        throw new ApexTraceSetupError('debug-level-create-failed', createResult.errors.map((e) => e.message).join(', '));
+    }
+    return createResult.id;
+}
+/** @returns The Id and expiration date of the DEVELOPER_LOG trace flag created/updated for `userId`. @throws {ApexTraceSetupError} `invalid-date-range`/`trace-flag-create-failed`. */
+async function findOrUpdateTraceFlag(connection, userId, debugLevelId, options) {
+    const traceFlagResult = await connection.tooling.query(`SELECT Id FROM TraceFlag WHERE LogType = 'DEVELOPER_LOG' AND TracedEntityId = '${userId}'`);
+    const startDate = options.startDate ?? new Date().toISOString();
+    const expirationDate = options.endDate ?? new Date(new Date(startDate).getTime() + TRACE_DURATION_MS).toISOString();
+    if (new Date(expirationDate).getTime() <= new Date(startDate).getTime()) {
+        throw new ApexTraceSetupError('invalid-date-range', `The end date (${expirationDate}) must be after the start date (${startDate}).`, [expirationDate, startDate]);
+    }
+    if (traceFlagResult.records.length > 0) {
+        const traceFlagId = traceFlagResult.records[0].Id;
+        await connection.tooling.sobject('TraceFlag').update({
+            Id: traceFlagId,
+            DebugLevelId: debugLevelId,
+            StartDate: startDate,
+            ExpirationDate: expirationDate,
+        });
+        return { traceFlagId, expirationDate };
+    }
+    const createResult = await connection.tooling.sobject('TraceFlag').create({
+        TracedEntityId: userId,
+        LogType: 'DEVELOPER_LOG',
+        DebugLevelId: debugLevelId,
+        StartDate: startDate,
+        ExpirationDate: expirationDate,
+    });
+    if (!createResult.success) {
+        throw new ApexTraceSetupError('trace-flag-create-failed', createResult.errors.map((e) => e.message).join(', '));
+    }
+    return { traceFlagId: createResult.id, expirationDate };
+}
+/**
+ * Creates or updates a DEVELOPER_LOG trace flag for a target user. The target user is the one
+ * `connection` authenticates as by default, or the user identified by `options.onBehalfOf` if
+ * given. By default the trace flag uses the FINEST/FINER `ReplayDebuggerLevels` debug level
+ * suitable for the Apex Replay Debugger and runs for 24 hours starting now;
+ * `options.logLevel`/`startDate`/`endDate` override those defaults.
+ *
+ * @param connection - The org connection to configure the trace flag in.
+ * @param options - See `ApexTraceSetupOptions`.
+ * @param onPhase - Called as each of the three phases (finding the user, checking the debug
+ * level, configuring the trace flag) starts — a caller (the CLI) can use this to update a
+ * spinner. Optional; has no effect on the operation itself.
+ * @returns The IDs of the debug level and trace flag that were created or updated, and the trace
+ * flag's new expiration date.
+ * @throws {ApexTraceSetupError} See `ApexTraceSetupErrorCode`.
+ */
+export async function setupApexTrace(connection, options = {}, onPhase) {
+    onPhase?.('finding-user');
+    const userId = await findTraceTargetUserId(connection, options.onBehalfOf);
+    onPhase?.('checking-debug-level');
+    const debugLevelId = await findOrCreateDebugLevel(connection, options.logLevel);
+    onPhase?.('configuring-trace-flag');
+    const { traceFlagId, expirationDate } = await findOrUpdateTraceFlag(connection, userId, debugLevelId, options);
+    return { userId, debugLevelId, traceFlagId, expirationDate };
+}
+//# sourceMappingURL=apexTraceSetup.js.map

package/lib/common/apexTraceSetup.js.map

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

package/lib/common/apexTraceSilence.d.ts

@@ -0,0 +1,65 @@
+import type { Connection } from '@salesforce/core';
+/** Classes silenced by the `fflib` preset. */
+export declare const FFLIB_CLASSES: string[];
+/** Classes silenced by the `at4dx` preset. */
+export declare const AT4DX_CLASSES: string[];
+/** Classes silenced by the `forceDi` preset. */
+export declare const FORCE_DI_CLASSES: string[];
+/** The trace flag created to silence debug logs for a single Apex class. */
+export type ApexTraceSilenceResult = {
+    class: string;
+    classId: string;
+    traceFlagId: string;
+};
+/** Everything `silenceApexClasses` found out along the way, beyond the classes it actually silenced — for a CLI (or other) caller to report however it likes. */
+export type ApexTraceSilenceOutcome = {
+    results: ApexTraceSilenceResult[];
+    /** Requested class names that don't exist as an `ApexClass` in the org. */
+    missingClassNames: string[];
+    /** A class that was found but whose trace flag couldn't be created/updated, with the API's error text and which of the two operations was attempted. */
+    failures: Array<{
+        class: string;
+        action: 'create' | 'update';
+        error: string;
+    }>;
+};
+/** The error conditions `resolveClasses`/`silenceApexClasses` signal structurally (via `code`) rather than by message text, so a `Messages`-based caller (the CLI) can map each one to its own error key without string-matching. */
+export type ApexTraceSilenceErrorCode = 'invalid-classes-file' | 'no-classes-specified' | 'debug-level-create-failed';
+export declare class ApexTraceSilenceError extends Error {
+    readonly code: ApexTraceSilenceErrorCode;
+    constructor(code: ApexTraceSilenceErrorCode, message: string);
+}
+/**
+ * Resolve the list of Apex class names to silence from an explicit list, a classes-file path (a
+ * JSON config matching {@link ClassesToSilenceSchema}), and the `fflib`/`at4dx`/`forceDi` built-in
+ * presets. All sources are combined and deduplicated.
+ *
+ * @param classNames - Explicit class names (e.g. from a `--classes` flag already split on commas).
+ * @param classesFilePath - Path to a JSON config file, if one was given.
+ * @param presets - Which of the built-in class presets were requested.
+ * @returns The resolved, trimmed, deduplicated list of Apex class names.
+ * @throws {ApexTraceSilenceError} `invalid-classes-file` if `classesFilePath` was given but fails
+ * schema validation.
+ */
+export declare function resolveClasses(classNames: string[], classesFilePath: string | undefined, presets: {
+    fflib: boolean;
+    at4dx: boolean;
+    forceDi: boolean;
+}): string[];
+/**
+ * Creates or updates a 24-hour CLASS_TRACING trace flag with a fully suppressed (NONE) debug level
+ * for each of `classNames`, preventing those classes from generating debug log output. A class
+ * that already has a trace flag has its expiration extended instead of getting a duplicate.
+ *
+ * @param connection - The org connection to silence classes in.
+ * @param classNames - The Apex class names to silence — see `resolveClasses`.
+ * @param onPhase - Called as each of the three phases (checking the debug level, finding the
+ * classes, writing trace flags) starts — a caller (the CLI) can use this to update a spinner.
+ * Optional; has no effect on the operation itself.
+ * @returns The trace flag created/updated per successfully-silenced class, plus any class names
+ * that don't exist in the org and any per-class create/update failures.
+ * @throws {ApexTraceSilenceError} `no-classes-specified` if `classNames` is empty,
+ * `debug-level-create-failed` if the shared `Silence` debug level doesn't exist yet and couldn't be
+ * created.
+ */
+export declare function silenceApexClasses(connection: Connection, classNames: string[], onPhase?: (phase: 'checking-debug-level' | 'finding-classes' | 'creating-trace-flags') => void): Promise<ApexTraceSilenceOutcome>;

package/lib/common/apexTraceSilence.js

@@ -0,0 +1,171 @@
+/*
+ * Copyright (c) 2026, Clay Chipps.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { loadJsonConfigSync } from '@simplysf/simply-core';
+import { ClassesToSilenceSchema } from './schemas/classesToSilence.js';
+/** DeveloperName used for the fully-suppressed (NONE) debug level created for class silencing. */
+const DEBUG_LEVEL_NAME = 'Silence';
+/** How long a configured trace flag stays active before expiring, in milliseconds (24 hours). */
+const TRACE_DURATION_MS = 24 * 60 * 60 * 1000;
+/** Classes silenced by the `fflib` preset. */
+export const FFLIB_CLASSES = ['fflib_SObjectDescribe', 'fflib_SObjectDomain'];
+/** Classes silenced by the `at4dx` preset. */
+export const AT4DX_CLASSES = ['ApplicationSObjectDomain'];
+/** Classes silenced by the `forceDi` preset. */
+export const FORCE_DI_CLASSES = ['di_Binding', 'di_Module', 'di_PlatformCache', 'di_Injector'];
+export class ApexTraceSilenceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ApexTraceSilenceError';
+        this.code = code;
+    }
+}
+/**
+ * Resolve the list of Apex class names to silence from an explicit list, a classes-file path (a
+ * JSON config matching {@link ClassesToSilenceSchema}), and the `fflib`/`at4dx`/`forceDi` built-in
+ * presets. All sources are combined and deduplicated.
+ *
+ * @param classNames - Explicit class names (e.g. from a `--classes` flag already split on commas).
+ * @param classesFilePath - Path to a JSON config file, if one was given.
+ * @param presets - Which of the built-in class presets were requested.
+ * @returns The resolved, trimmed, deduplicated list of Apex class names.
+ * @throws {ApexTraceSilenceError} `invalid-classes-file` if `classesFilePath` was given but fails
+ * schema validation.
+ */
+export function resolveClasses(classNames, classesFilePath, presets) {
+    const classes = [...classNames];
+    if (classesFilePath) {
+        const parsed = loadJsonConfigSync(classesFilePath, ClassesToSilenceSchema);
+        if (!parsed.success) {
+            throw new ApexTraceSilenceError('invalid-classes-file', parsed.message);
+        }
+        classes.push(...parsed.data.classes);
+    }
+    if (presets.fflib) {
+        classes.push(...FFLIB_CLASSES);
+    }
+    if (presets.at4dx) {
+        classes.push(...AT4DX_CLASSES);
+    }
+    if (presets.forceDi) {
+        classes.push(...FORCE_DI_CLASSES);
+    }
+    return [...new Set(classes)];
+}
+/**
+ * Creates or updates a 24-hour CLASS_TRACING trace flag with a fully suppressed (NONE) debug level
+ * for each of `classNames`, preventing those classes from generating debug log output. A class
+ * that already has a trace flag has its expiration extended instead of getting a duplicate.
+ *
+ * @param connection - The org connection to silence classes in.
+ * @param classNames - The Apex class names to silence — see `resolveClasses`.
+ * @param onPhase - Called as each of the three phases (checking the debug level, finding the
+ * classes, writing trace flags) starts — a caller (the CLI) can use this to update a spinner.
+ * Optional; has no effect on the operation itself.
+ * @returns The trace flag created/updated per successfully-silenced class, plus any class names
+ * that don't exist in the org and any per-class create/update failures.
+ * @throws {ApexTraceSilenceError} `no-classes-specified` if `classNames` is empty,
+ * `debug-level-create-failed` if the shared `Silence` debug level doesn't exist yet and couldn't be
+ * created.
+ */
+export async function silenceApexClasses(connection, classNames, onPhase) {
+    if (classNames.length === 0) {
+        throw new ApexTraceSilenceError('no-classes-specified', 'No Apex classes were specified to silence.');
+    }
+    onPhase?.('checking-debug-level');
+    const debugLevelResult = await connection.tooling.query(`SELECT Id FROM DebugLevel WHERE DeveloperName = '${DEBUG_LEVEL_NAME}'`);
+    let debugLevelId;
+    if (debugLevelResult.records.length > 0) {
+        debugLevelId = debugLevelResult.records[0].Id;
+    }
+    else {
+        const createResult = await connection.tooling.sobject('DebugLevel').create({
+            DeveloperName: DEBUG_LEVEL_NAME,
+            MasterLabel: DEBUG_LEVEL_NAME,
+            ApexCode: 'NONE',
+            ApexProfiling: 'NONE',
+            Callout: 'NONE',
+            Database: 'NONE',
+            System: 'NONE',
+            Validation: 'NONE',
+            Visualforce: 'NONE',
+            Workflow: 'NONE',
+        });
+        if (!createResult.success) {
+            throw new ApexTraceSilenceError('debug-level-create-failed', createResult.errors.map((e) => e.message).join(', '));
+        }
+        debugLevelId = createResult.id;
+    }
+    onPhase?.('finding-classes');
+    const classesClause = classNames.map((className) => `'${className}'`).join(',');
+    const classResult = await connection.tooling.query(`SELECT Id, Name FROM ApexClass WHERE Name IN (${classesClause})`);
+    if (classResult.records.length === 0) {
+        return { results: [], missingClassNames: classNames, failures: [] };
+    }
+    const foundNames = new Set(classResult.records.map((record) => record.Name));
+    const missingClassNames = classNames.filter((className) => !foundNames.has(className));
+    const now = new Date();
+    const expiration = new Date(now.getTime() + TRACE_DURATION_MS);
+    const startDate = now.toISOString();
+    const expirationDate = expiration.toISOString();
+    const classIdsClause = classResult.records.map((record) => `'${record.Id}'`).join(',');
+    const existingTraceFlagResult = await connection.tooling.query(`SELECT Id, TracedEntityId FROM TraceFlag WHERE LogType = 'CLASS_TRACING' AND TracedEntityId IN (${classIdsClause})`);
+    const existingTraceFlagIdByClassId = new Map(existingTraceFlagResult.records.map((record) => [record.TracedEntityId, record.Id]));
+    const results = [];
+    const failures = [];
+    onPhase?.('creating-trace-flags');
+    for (const classRecord of classResult.records) {
+        const existingTraceFlagId = existingTraceFlagIdByClassId.get(classRecord.Id);
+        if (existingTraceFlagId) {
+            // eslint-disable-next-line no-await-in-loop -- trace flags are written sequentially, matching the CLI's per-class progress reporting
+            const updateResult = await connection.tooling.sobject('TraceFlag').update({
+                Id: existingTraceFlagId,
+                DebugLevelId: debugLevelId,
+                StartDate: startDate,
+                ExpirationDate: expirationDate,
+            });
+            if (!updateResult.success) {
+                failures.push({
+                    class: classRecord.Name,
+                    action: 'update',
+                    error: updateResult.errors.map((e) => e.message).join(', '),
+                });
+                continue;
+            }
+            results.push({ class: classRecord.Name, classId: classRecord.Id, traceFlagId: existingTraceFlagId });
+            continue;
+        }
+        // eslint-disable-next-line no-await-in-loop -- trace flags are written sequentially, matching the CLI's per-class progress reporting
+        const createResult = await connection.tooling.sobject('TraceFlag').create({
+            StartDate: startDate,
+            ExpirationDate: expirationDate,
+            DebugLevelId: debugLevelId,
+            TracedEntityId: classRecord.Id,
+            LogType: 'CLASS_TRACING',
+        });
+        if (!createResult.success) {
+            failures.push({
+                class: classRecord.Name,
+                action: 'create',
+                error: createResult.errors.map((e) => e.message).join(', '),
+            });
+            continue;
+        }
+        results.push({ class: classRecord.Name, classId: classRecord.Id, traceFlagId: createResult.id });
+    }
+    return { results, missingClassNames, failures };
+}
+//# sourceMappingURL=apexTraceSilence.js.map

package/lib/common/apexTraceSilence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apexTraceSilence.js","sourceRoot":"","sources":["../../src/common/apexTraceSilence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAEvE,kGAAkG;AAClG,MAAM,gBAAgB,GAAG,SAAS,CAAC;AACnC,iGAAiG;AACjG,MAAM,iBAAiB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE9C,8CAA8C;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,uBAAuB,EAAE,qBAAqB,CAAC,CAAC;AAC9E,8CAA8C;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,0BAA0B,CAAC,CAAC;AAC1D,gDAAgD;AAChD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,CAAC,CAAC;AAqB/F,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9B,IAAI,CAA4B;IAEhD,YAAmB,IAA+B,EAAE,OAAe;QACjE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,UAAoB,EACpB,eAAmC,EACnC,OAA6D;IAE7D,MAAM,OAAO,GAAa,CAAC,GAAG,UAAU,CAAC,CAAC;IAE1C,IAAI,eAAe,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,kBAAkB,CAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC;QAE3E,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,qBAAqB,CAAC,sBAAsB,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1E,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,UAAsB,EACtB,UAAoB,EACpB,OAA8F;IAE9F,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,qBAAqB,CAAC,sBAAsB,EAAE,4CAA4C,CAAC,CAAC;IACxG,CAAC;IAED,OAAO,EAAE,CAAC,sBAAsB,CAAC,CAAC;IAClC,MAAM,gBAAgB,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,KAAK,CACrD,oDAAoD,gBAAgB,GAAG,CACxE,CAAC;IAEF,IAAI,YAAoB,CAAC;IAEzB,IAAI,gBAAgB,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,YAAY,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChD,CAAC;SAAM,CAAC;QACN,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC;YACzE,aAAa,EAAE,gBAAgB;YAC/B,WAAW,EAAE,gBAAgB;YAC7B,QAAQ,EAAE,MAAM;YAChB,aAAa,EAAE,MAAM;YACrB,OAAO,EAAE,MAAM;YACf,QAAQ,EAAE,MAAM;YAChB,MAAM,EAAE,MAAM;YACd,UAAU,EAAE,MAAM;YAClB,WAAW,EAAE,MAAM;YACnB,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAC;QAEH,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;YAC1B,MAAM,IAAI,qBAAqB,CAC7B,2BAA2B,EAC3B,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CACrD,CAAC;QACJ,CAAC;QAED,YAAY,GAAG,YAAY,CAAC,EAAE,CAAC;IACjC,CAAC;IAED,OAAO,EAAE,CAAC,iBAAiB,CAAC,CAAC;IAC7B,MAAM,aAAa,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChF,MAAM,WAAW,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,KAAK,CAChD,iDAAiD,aAAa,GAAG,CAClE,CAAC;IAEF,IAAI,WAAW,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,iBAAiB,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACtE,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7E,MAAM,iBAAiB,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;IAEvF,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,UAAU,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,iBAAiB,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,cAAc,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IAEhD,MAAM,cAAc,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvF,MAAM,uBAAuB,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,KAAK,CAC5D,mGAAmG,cAAc,GAAG,CACrH,CAAC;IACF,MAAM,4BAA4B,GAAG,IAAI,GAAG,CAC1C,uBAAuB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CACpF,CAAC;IAEF,MAAM,OAAO,GAA6B,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAyE,EAAE,CAAC;IAE1F,OAAO,EAAE,CAAC,sBAAsB,CAAC,CAAC;IAClC,KAAK,MAAM,WAAW,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;QAC9C,MAAM,mBAAmB,GAAG,4BAA4B,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAE7E,IAAI,mBAAmB,EAAE,CAAC;YACxB,qIAAqI;YACrI,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC;gBACxE,EAAE,EAAE,mBAAmB;gBACvB,YAAY,EAAE,YAAY;gBAC1B,SAAS,EAAE,SAAS;gBACpB,cAAc,EAAE,cAAc;aAC/B,CAAC,CAAC;YAEH,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;gBAC1B,QAAQ,CAAC,IAAI,CAAC;oBACZ,KAAK,EAAE,WAAW,CAAC,IAAI;oBACvB,MAAM,EAAE,QAAQ;oBAChB,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;iBAC5D,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,EAAE,WAAW,EAAE,mBAAmB,EAAE,CAAC,CAAC;YACrG,SAAS;QACX,CAAC;QAED,qIAAqI;QACrI,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC;YACxE,SAAS,EAAE,SAAS;YACpB,cAAc,EAAE,cAAc;YAC9B,YAAY,EAAE,YAAY;YAC1B,cAAc,EAAE,WAAW,CAAC,EAAE;YAC9B,OAAO,EAAE,eAAe;SACzB,CAAC,CAAC;QAEH,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,WAAW,CAAC,IAAI;gBACvB,MAAM,EAAE,QAAQ;gBAChB,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;aAC5D,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,EAAE,WAAW,EAAE,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC;IACnG,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAC;AAClD,CAAC"}

package/lib/common/schemas/classesToSilence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classesToSilence.js","sourceRoot":"","sources":["../../../src/common/schemas/classesToSilence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+FAA+F;AAC/F,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CACpC,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@simplysf/simply-apex",
   "description": "Utilities for working with Apex",
-  "version": "1.6.8",
+  "version": "1.6.10",
   "author": "@ClayChipps",
   "homepage": "https://github.com/SimplySF/simply-node",
   "bugs": "https://github.com/SimplySF/simply-node/issues",
@@ -87,7 +87,6 @@
     "compile": "wireit",
     "fix-license": "eslint src test --fix --rule \"header/header: [2]\"",
     "format": "wireit",
-    "link-check": "wireit",
     "lint": "wireit",
     "readme": "oclif readme --no-aliases",
     "test": "wireit",
@@ -148,8 +147,7 @@
         "test:only",
         "test:command-reference",
         "lint",
-        "test:json-schema",
-        "link-check"
+        "test:json-schema"
       ]
     },
     "test:command-reference": {
@@ -206,16 +204,7 @@
         "!*.nut.ts"
       ],
       "output": []
-    },
-    "link-check": {
-      "command": "node -e \"process.exit(process.env.CI ? 0 : 1)\" || linkinator \"**/*.md\" --skip \"CHANGELOG.md|node_modules|test/|confluence.internal.salesforce.com|my.salesforce.com|localhost|example\\.(com|org|net)|github\\.com/SimplySF/simply-node|raw\\.githubusercontent\\.com/SimplySF/simply-node|blob/.*/lib/|%s\" --markdown --retry --directory-listing --verbosity error",
-      "files": [
-        "./*.md",
-        "./!(CHANGELOG).md",
-        "messages/**/*.md"
-      ],
-      "output": []
     }
   },
-  "gitHead": "b488b999d007c0036e86fda6dfa3092f103224ec"
+  "gitHead": "6665a2b7d6ae7347e2658a2958535052240b4ad8"
 }

package/lib/schemas/silence/classesToSilence.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"classesToSilence.js","sourceRoot":"","sources":["../../../src/schemas/silence/classesToSilence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+FAA+F;AAC/F,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CACpC,CAAC,CAAC"}