feat: enhance field usage analysis and permission export functionality

- Added `truncated` flag to `FieldUsageStat` and `ScanFieldUsageResult` to indicate incomplete field data.
- Updated `runFieldUsageQueryForObjects` to handle per-field truncation and reflect it in the UI.
- Introduced tests for permission export findings to suppress warnings when permissions are truncated.
- Enhanced `runPermissionExport` to dynamically select available system permission fields based on the org's capabilities.
- Modified SOQL query generation to prevent invalid field errors by only including existing permission fields.
- Improved field usage analysis view to display truncated status and provide user feedback on scanned percentages.
- Refactored destructive delete eligibility checks to consider field scan truncation.
- Added unit tests for `queryWithRecordBudget` to ensure correct handling of record limits and pagination.

Author: paustint

apps/api/src/app/db/user.db.ts

@@ -87,6 +87,7 @@ const UserFacingProfileSelect = {
   },
   entitlements: {
     select: {
+      analysisTools: true,
       chromeExtension: true,
       desktop: true,
       googleDrive: true,
@@ -113,6 +114,7 @@ const UserFacingProfileSelect = {
           billingStatus: true,
           entitlements: {
             select: {
+              analysisTools: true,
               chromeExtension: true,
               desktop: true,
               googleDrive: true,
@@ -149,6 +151,7 @@ export const findByIdWithSubscriptions = (id: string) => {
       name: true,
       entitlements: {
         select: {
+          analysisTools: true,
           chromeExtension: true,
           desktop: true,
           googleDrive: true,

libs/features/analysis-shared/src/field-usage/__tests__/run-field-usage.spec.ts

@@ -292,6 +292,67 @@ describe('runFieldUsageQueryForObjects (streaming)', () => {
     expect(queryMock.mock.calls[0][1]).toContain('COUNT(');
   });
 
+  it('marks only row-scanned fields truncated; COUNT-based fields stay exact', async () => {
+    describeMock.mockResolvedValue({
+      data: {
+        label: 'Account',
+        queryable: true,
+        custom: false,
+        fields: [
+          { name: 'Id', label: 'Id', type: 'id', calculated: false, custom: false, autoNumber: false, length: 18, scale: 0 },
+          { name: 'LastModifiedDate', label: 'LMD', type: 'datetime', calculated: false, custom: false, autoNumber: false, scale: 0 },
+          {
+            name: 'Custom_Text__c',
+            label: 'Text',
+            type: 'string',
+            calculated: false,
+            custom: true,
+            autoNumber: false,
+            length: 255,
+            scale: 0,
+            aggregatable: true,
+          },
+          {
+            name: 'Active__c',
+            label: 'Active',
+            type: 'boolean',
+            calculated: false,
+            custom: true,
+            autoNumber: false,
+            scale: 0,
+            aggregatable: true, // booleans never COUNT — still row-scanned
+          },
+        ],
+      },
+    });
+
+    // One page larger than the 100K row budget forces the boolean's row scan to truncate.
+    const overBudgetPage = Array.from({ length: 100_001 }, (_, index) => ({
+      Id: `001${String(index).padStart(15, '0')}`,
+      LastModifiedDate: '2026-01-01T00:00:00.000+0000',
+      Active__c: index % 2 === 0,
+    }));
+    queryMock.mockImplementation(async (_org: unknown, soql: string) => {
+      if (typeof soql === 'string' && soql.includes('COUNT(')) {
+        return { queryResults: { done: true, totalSize: 1, records: [{ total: 250_000, c0: 90_000 }] } };
+      }
+      return { queryResults: { done: true, records: overBudgetPage } };
+    });
+
+    const result = await runFieldUsageQueryForObjects(fakeOrg, ['Account']);
+
+    const account = result.objects.Account;
+    expect(account.queryTruncated).toBe(true);
+    expect(result.anyQueryTruncated).toBe(true);
+    // The scanned boolean hit the row budget — flagged per-field.
+    expect(account.fieldUsage.Active__c.truncated).toBe(true);
+    expect(account.fieldUsage.Active__c.scanned).toBe(100_000);
+    // The COUNT-based field is exact across all 250K rows despite the sibling scan truncating.
+    expect(account.fieldUsage.Custom_Text__c.truncated).toBe(false);
+    expect(account.fieldUsage.Custom_Text__c.filled).toBe(90_000);
+    expect(account.fieldUsage.Custom_Text__c.scanned).toBe(250_000);
+  });
+
   it('throws when the cancellation signal trips between objects', async () => {
     describeMock.mockResolvedValue(buildDescribe());
     queryMock.mockResolvedValue(buildPage([], null));

libs/features/analysis-shared/src/field-usage/run-field-usage.ts

@@ -26,6 +26,13 @@ export interface FieldUsageStat {
    * (avoids `filled > totalRecords` when row counts drift between sequential chunk queries).
    */
   scanned: number;
+  /**
+   * Whether THIS field's numbers may be incomplete. COUNT-aggregated fields are always exact
+   * (`false`); row-scanned fields inherit their chunk's row-budget truncation. Lets the UI avoid
+   * blocking delete-eligibility (or warning) on exact fields just because an unrelated field's
+   * scan on the same object was truncated.
+   */
+  truncated: boolean;
 }
 
 export interface FieldUsageObjectPayload {
@@ -300,6 +307,8 @@ interface ScanFieldUsageResult {
   scannedByField: Record<string, number>;
   maxLmd: Record<string, string | null>;
   truncated: boolean;
+  /** Per-field truncation — every field in a chunk shares that chunk's row-budget outcome. */
+  truncatedByField: Record<string, boolean>;
   /** Rows scanned by the first chunk — the object-level "records scanned" when no COUNT total is available. */
   scanTotal: number;
 }
@@ -319,6 +328,7 @@ async function scanFieldUsage(
   const filled: Record<string, number> = Object.fromEntries(fieldNames.map((name) => [name, 0]));
   const maxLmd: Record<string, string | null> = Object.fromEntries(fieldNames.map((name) => [name, null]));
   const scannedByField: Record<string, number> = Object.fromEntries(fieldNames.map((name) => [name, 0]));
+  const truncatedByField: Record<string, boolean> = Object.fromEntries(fieldNames.map((name) => [name, false]));
   let truncated = false;
   let scanTotal = 0;
   const chunks = buildFieldChunks(fieldNames, objectApiName);
@@ -348,6 +358,7 @@ async function scanFieldUsage(
 
     for (const fieldName of chunkNames) {
       scannedByField[fieldName] = chunkRecordCount;
+      truncatedByField[fieldName] = result.truncated;
     }
     if (result.truncated) {
       truncated = true;
@@ -357,7 +368,7 @@ async function scanFieldUsage(
     }
   }
 
-  return { filled, scannedByField, maxLmd, truncated, scanTotal };
+  return { filled, scannedByField, maxLmd, truncated, truncatedByField, scanTotal };
 }
 
 /**
@@ -424,6 +435,7 @@ export async function runFieldUsageQueryForObjects(
       const filled: Record<string, number> = {};
       const maxLmdWhenFilled: Record<string, string | null> = {};
       const scannedByField: Record<string, number> = {};
+      const truncatedByField: Record<string, boolean> = {};
       let queryTruncated = false;
       let countTotal: number | null = null;
 
@@ -447,6 +459,7 @@ export async function runFieldUsageQueryForObjects(
           // there is no truncation. COUNT cannot report a per-field "latest modified", so it stays null.
           scannedByField[name] = countResult.total;
           maxLmdWhenFilled[name] = null;
+          truncatedByField[name] = false;
         }
       }
 
@@ -459,6 +472,7 @@ export async function runFieldUsageQueryForObjects(
           filled[name] = scanResult.filled[name] ?? 0;
           scannedByField[name] = scanResult.scannedByField[name] ?? 0;
           maxLmdWhenFilled[name] = scanResult.maxLmd[name] ?? null;
+          truncatedByField[name] = scanResult.truncatedByField[name] ?? false;
         }
         if (scanResult.truncated) {
           queryTruncated = true;
@@ -480,6 +494,7 @@ export async function runFieldUsageQueryForObjects(
           // Clamp defensively so display never shows >100% / <0% from any count drift.
           pct: Math.max(0, Math.min(100, rawPct)),
           latestFilledRowModified: maxLmdWhenFilled[name] ?? null,
+          truncated: truncatedByField[name] ?? false,
         };
       }
 

libs/features/analysis-shared/src/permission-export/__tests__/build-permission-export-findings.spec.ts

@@ -291,6 +291,52 @@ describe('buildPermissionExportFindings — new findings', () => {
   });
 });
 
+describe('buildPermissionExportFindings — truncation and scope suppression', () => {
+  const parentId = '0PS1';
+
+  it('does not emit OLS_*_NO_FLS_ROWS when field permissions were truncated', () => {
+    const objectPermissions = [{ ParentId: parentId, SobjectType: 'Account', PermissionsRead: true, PermissionsEdit: true }];
+    const codes = buildPermissionExportFindings(objectPermissions, [], { truncatedCategories: ['fieldPermissions'] }).map((f) => f.code);
+    expect(codes).not.toContain('OLS_READ_NO_FLS_ROWS');
+    expect(codes).not.toContain('OLS_EDIT_NO_FLS_ROWS');
+  });
+
+  it('does not emit FLS_WITHOUT_OLS_ROW when object permissions were truncated', () => {
+    const fieldPermissions = [{ ParentId: parentId, SobjectType: 'Case', Field: 'Case.Subject', PermissionsRead: true }];
+    const codes = buildPermissionExportFindings([], fieldPermissions, { truncatedCategories: ['objectPermissions'] }).map((f) => f.code);
+    expect(codes).not.toContain('FLS_WITHOUT_OLS_ROW');
+  });
+
+  it('does not emit TAB_VISIBLE_NO_OBJECT_READ when object permissions were truncated', () => {
+    const context = {
+      permissionSetTabSettings: [{ ParentId: parentId, Name: 'standard-Account', Visibility: 'DefaultOn' }],
+      truncatedCategories: ['objectPermissions'],
+    };
+    const codes = buildPermissionExportFindings([], [], context).map((f) => f.code);
+    expect(codes).not.toContain('TAB_VISIBLE_NO_OBJECT_READ');
+  });
+
+  it('only evaluates tab findings for in-scope objects when the export was object-scoped', () => {
+    const context = {
+      permissionSetTabSettings: [
+        { ParentId: parentId, Name: 'standard-Account', Visibility: 'DefaultOn' },
+        { ParentId: parentId, Name: 'standard-Contact', Visibility: 'DefaultOn' },
+      ],
+      objectScope: ['Account'],
+    };
+    const findings = buildPermissionExportFindings([], [], context).filter((f) => f.code === 'TAB_VISIBLE_NO_OBJECT_READ');
+    // Contact tab is skipped — its ObjectPermissions rows were never fetched, so "no access" cannot be proven.
+    expect(findings).toHaveLength(1);
+    expect(findings[0].objectApiName).toBe('Account');
+  });
+
+  it('does not emit OLS_READ_NO_FLS_ROWS when View All Fields is granted (intentional no-FLS setup)', () => {
+    const objectPermissions = [{ ParentId: parentId, SobjectType: 'Account', PermissionsRead: true, PermissionsViewAllFields: true }];
+    const codes = buildPermissionExportFindings(objectPermissions, []).map((f) => f.code);
+    expect(codes).not.toContain('OLS_READ_NO_FLS_ROWS');
+  });
+});
+
 describe('buildIssueCodeSummary', () => {
   it('aggregates counts by code', () => {
     const summary = buildIssueCodeSummary([

libs/features/analysis-shared/src/permission-export/__tests__/run-permission-export.spec.ts

@@ -1,10 +1,12 @@
+import { HIGH_RISK_SYSTEM_PERMISSIONS } from '@jetstream/shared/constants';
 import type { SalesforceOrgUi } from '@jetstream/types';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { runPermissionExport } from '../run-permission-export';
 
-const { mockedQuery, mockedQueryMore } = vi.hoisted(() => ({
+const { mockedQuery, mockedQueryMore, mockedDescribeSObject } = vi.hoisted(() => ({
   mockedQuery: vi.fn(),
   mockedQueryMore: vi.fn(),
+  mockedDescribeSObject: vi.fn(),
 }));
 
 vi.mock('@jetstream/shared/data', async (importOriginal) => {
@@ -44,10 +46,21 @@ vi.mock('@jetstream/shared/data', async (importOriginal) => {
     ...actual,
     query: mockedQuery,
     queryMore: mockedQueryMore,
+    describeSObject: mockedDescribeSObject,
     queryWithRecordBudget,
   };
 });
 
+/** Builds a PermissionSet describe response containing the provided `Permissions*` columns. */
+function permissionSetDescribe(permissionFieldNames: string[]) {
+  return {
+    data: {
+      name: 'PermissionSet',
+      fields: ['Id', 'Name', 'Label', ...permissionFieldNames].map((name) => ({ name })),
+    },
+  } as any;
+}
+
 function done<T>(records: T[]) {
   return {
     queryResults: {
@@ -68,6 +81,8 @@ describe('runPermissionExport', () => {
   beforeEach(() => {
     mockedQuery.mockReset();
     mockedQueryMore.mockReset();
+    mockedDescribeSObject.mockReset();
+    mockedDescribeSObject.mockResolvedValue(permissionSetDescribe(HIGH_RISK_SYSTEM_PERMISSIONS.map(({ field }) => field)));
   });
 
   it('returns an empty merged result when no valid parent ids are provided', async () => {
@@ -180,4 +195,52 @@ describe('runPermissionExport', () => {
     await expect(runPermissionExport(ORG, [PROFILE_PERM_SET_ID], [], { isCanceled: () => true })).rejects.toThrow('Job canceled');
     expect(mockedQuery).not.toHaveBeenCalled();
   });
+
+  it('omits system permission columns the org does not have from the PermissionSet SOQL', async () => {
+    mockedDescribeSObject.mockResolvedValue(permissionSetDescribe(['PermissionsModifyAllData', 'PermissionsViewAllData']));
+    mockedQuery.mockResolvedValue(done([]));
+
+    await runPermissionExport(ORG, [], [PERM_SET_ID]);
+
+    const permissionSetSoql = mockedQuery.mock.calls[0][1] as string;
+    expect(permissionSetSoql).toContain('PermissionsModifyAllData');
+    expect(permissionSetSoql).toContain('PermissionsViewAllData');
+    expect(permissionSetSoql).not.toContain('PermissionsAuthorApex');
+    expect(permissionSetSoql).not.toContain('PermissionsManageUsers');
+  });
+
+  it('selects the full system permission catalog when the PermissionSet describe fails', async () => {
+    mockedDescribeSObject.mockRejectedValue(new Error('describe unavailable'));
+    mockedQuery.mockResolvedValue(done([]));
+
+    await runPermissionExport(ORG, [], [PERM_SET_ID]);
+
+    const permissionSetSoql = mockedQuery.mock.calls[0][1] as string;
+    for (const { field } of HIGH_RISK_SYSTEM_PERMISSIONS) {
+      expect(permissionSetSoql).toContain(field);
+    }
+  });
+
+  it('never emits a lower percent after totalSteps grows for group chunks', async () => {
+    const permissionSetRows = [{ Id: PERM_SET_ID, Name: 'CustomPermSet', IsOwnedByProfile: false }];
+    const componentRows = [{ Id: '0PC000000000001', PermissionSetGroupId: GROUP_ID, PermissionSetId: PERM_SET_ID }];
+    mockedQuery
+      .mockResolvedValueOnce(done(permissionSetRows))
+      .mockResolvedValueOnce(done([])) // object permissions
+      .mockResolvedValueOnce(done([])) // field permissions
+      .mockResolvedValueOnce(done([])) // tab settings
+      .mockResolvedValueOnce(done([])) // assignments
+      .mockResolvedValueOnce(done(componentRows))
+      .mockResolvedValueOnce(done([{ Id: GROUP_ID, DeveloperName: 'GroupA', MasterLabel: 'Group A' }]))
+      .mockResolvedValueOnce(done([]));
+
+    const onProgress = vi.fn();
+    await runPermissionExport(ORG, [], [PERM_SET_ID], { onProgress });
+
+    const percents = onProgress.mock.calls.map(([progress]) => progress.percent as number);
+    for (let i = 1; i < percents.length; i++) {
+      expect(percents[i]).toBeGreaterThanOrEqual(percents[i - 1]);
+    }
+    expect(percents.at(-1)).toBe(100);
+  });
 });