@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.10

package/lib/utils/formatting/object-list-display.d.ts

@@ -0,0 +1,225 @@
+import type { ObjectListResult, ObjectListItem, ObjectListSummary, NamespaceCount } from '../../services/ObjectListCommandService.js';
+import { type OrgIdentity } from '../../services/OrgInfoService.js';
+/**
+ * Enrichment flag configuration for conditional table columns.
+ */
+export type EnrichmentFlags = {
+    readonly withFields: boolean;
+    readonly withRecordTypes: boolean;
+    readonly withBusinessProcess: boolean;
+    readonly withReferences: boolean;
+    readonly withContactPoints: boolean;
+};
+/**
+ * Pre-computed column widths for right-alignment of numeric columns.
+ */
+export type ColumnWidths = {
+    readonly records: number;
+    readonly recordTypes: number;
+    readonly businessProcess: number;
+    readonly totalFields: number;
+    readonly custom: number;
+    readonly reference: number;
+    readonly cpTotal: number;
+    readonly cpEmail: number;
+    readonly cpPhone: number;
+    readonly cpUrl: number;
+};
+/**
+ * Contact point category totals across all objects.
+ */
+export type CpCategoryTotals = {
+    readonly email: number;
+    readonly phone: number;
+    readonly url: number;
+};
+/**
+ * Renders the record-count cell for an object, disclosing count provenance (CLI-4214).
+ *
+ * - `undefined` recordCount → the unknown-count placeholder (em dash). NEVER 0.
+ * - `recordCountProvenance === 'limits'` → APPROXIMATE: prefixed with `~`.
+ * - otherwise (authoritative `'queried'` or a count with no provenance) → plain number.
+ *
+ * @param obj - The object list item
+ * @returns The display string for the record count (unpadded)
+ */
+export declare function formatRecordCount(obj: ObjectListItem): string;
+/**
+ * Computes per-category contact point totals across all objects.
+ *
+ * @param objects - The object list items to aggregate
+ * @returns Totals for email, phone, and URL contact point fields
+ */
+export declare function computeCpCategoryTotals(objects: ObjectListItem[]): CpCategoryTotals;
+/**
+ * Displays the complete object list results in table format.
+ *
+ * Orchestrates all display sub-sections: org identity, active filters,
+ * summary box, namespace distribution, object table, and next steps.
+ *
+ * @param log - The logging function (typically `this.log.bind(this)`)
+ * @param data - The ObjectListResult from the service
+ * @param orgIdentity - The org identity data (optional)
+ * @param instanceUrl - The org instance URL (optional)
+ * @param username - The target org username for Next Steps commands
+ */
+export declare function displayResults(log: (msg: string) => void, data: ObjectListResult, orgIdentity?: OrgIdentity, instanceUrl?: string, username?: string): void;
+/**
+ * Displays the namespace distribution table.
+ *
+ * @param log - The logging function
+ * @param namespaceCounts - The namespace counts from the summary
+ */
+export declare function displayNamespaceDistribution(log: (msg: string) => void, namespaceCounts: NamespaceCount[]): void;
+/**
+ * Displays the objects table with enrichment columns, or empty state if no objects match.
+ *
+ * @param log - The logging function
+ * @param data - The full ObjectListResult (for filters and summary)
+ * @param objects - The sorted objects to display
+ */
+export declare function displayObjectsTable(log: (msg: string) => void, data: ObjectListResult, objects: ObjectListItem[]): void;
+/**
+ * Displays contact point field details (email, phone, URL field names) for each object
+ * that has at least one contact point field, rendered as a sub-section after the main table.
+ *
+ * @param log - The logging function
+ * @param objects - The objects to display contact points for
+ */
+export declare function displayContactPointDetails(log: (msg: string) => void, objects: ObjectListItem[]): void;
+/**
+ * Builds separator and total rows for the objects table.
+ *
+ * @param summary - The object list summary with aggregate counts
+ * @param colWidths - Pre-computed column widths
+ * @param enrichmentFlags - Active enrichment flags
+ * @param cpTotals - Contact point category totals
+ * @returns Separator and total row data
+ */
+export declare function buildTotalRows(summary: ObjectListSummary, colWidths: ColumnWidths, enrichmentFlags: EnrichmentFlags, cpTotals: CpCategoryTotals): {
+    separatorRow: Record<string, string>;
+    totalRow: Record<string, string>;
+};
+/**
+ * Pre-computes column widths for right-alignment of numeric columns.
+ * Includes summary totals in the max width calculation to prevent
+ * alignment drift when a total value is wider than any data value.
+ *
+ * @param objects - The objects to compute widths for
+ * @param enrichmentFlags - Active enrichment flags
+ * @param summary - The summary with aggregate totals
+ * @param cpTotals - Contact point category totals
+ * @returns Pre-computed column widths
+ */
+export declare function computeColWidths(objects: ObjectListItem[], enrichmentFlags: EnrichmentFlags, summary: ObjectListSummary, cpTotals: CpCategoryTotals): ColumnWidths;
+/**
+ * Formats a single object row for the table display, including optional enrichment columns.
+ *
+ * @param obj - The object list item to format
+ * @param colWidths - Pre-computed column widths for right-alignment
+ * @param enrichmentFlags - Active enrichment flags for conditional columns
+ * @returns A record of column key to formatted string value
+ */
+export declare function formatObjectRow(obj: ObjectListItem, colWidths: ColumnWidths, enrichmentFlags?: EnrichmentFlags): Record<string, string>;
+/**
+ * Gets table column definitions, including optional enrichment columns.
+ * Numeric columns use horizontalAlignment: 'right' for consistent rendering.
+ *
+ * @param enrichmentFlags - Active enrichment flags for conditional columns
+ * @returns Array of column definitions for makeTable
+ */
+export declare function getTableColumns(enrichmentFlags?: EnrichmentFlags): Array<{
+    key: string;
+    name: string;
+    horizontalAlignment?: 'left' | 'right';
+}>;
+/**
+ * Builds a list of human-readable descriptions for active filters.
+ *
+ * @param filters - The applied filter options from the service result
+ * @returns Array of filter description strings (empty if no filters active)
+ */
+export declare function getActiveFilters(filters: ObjectListResult['filters']): string[];
+/**
+ * Returns active filters ordered by selectivity (most restrictive first).
+ * Used in empty state display to help users identify which filter to relax.
+ *
+ * @param filters - The applied filter options from the service result
+ * @returns Array of filter flag strings ordered by selectivity
+ */
+export declare function getSelectiveFilters(filters: ObjectListResult['filters']): string[];
+/**
+ * Builds the command result for JSON output.
+ *
+ * @param data - The ObjectListResult from the service
+ * @param flags - The parsed command flags
+ * @param orgIdentity - The org identity data (optional)
+ * @param instanceUrl - The org instance URL (optional)
+ * @param metadata - Service metadata with duration
+ * @returns ObjectListCommandResult for JSON output
+ */
+export declare function buildCommandResult(data: ObjectListResult, flags: {
+    object?: string;
+    filter: 'all' | 'standard' | 'custom';
+    namespace?: string;
+    pattern?: string;
+    'with-records': boolean;
+    'without-records': boolean;
+    'with-owner': boolean;
+    'with-record-types': boolean;
+    'with-business-process': boolean;
+    'with-fields': boolean;
+    'with-references': boolean;
+    'with-contact-points': boolean;
+    classification: 'customer' | 'internal' | 'all';
+    'min-records'?: number;
+    sort: 'name' | 'recordCount' | 'label';
+    limit?: number;
+}, orgIdentity?: OrgIdentity, instanceUrl?: string, metadata?: {
+    duration?: number;
+}): {
+    success: boolean;
+    orgIdentity?: {
+        orgId: string;
+        orgName: string;
+        orgType: string;
+        isSandbox: boolean;
+        instanceUrl: string;
+        username: string;
+        namespacePrefix?: string;
+    };
+    summary: ObjectListSummary;
+    filters: {
+        object?: string;
+        filter?: string;
+        namespace?: string;
+        pattern?: string;
+        withRecords?: boolean;
+        withoutRecords?: boolean;
+        withOwner?: boolean;
+        withRecordTypes?: boolean;
+        withBusinessProcess?: boolean;
+        includeFieldCounts?: boolean;
+        includeReferences?: boolean;
+        withContactPoints?: boolean;
+        classification?: 'customer' | 'internal' | 'all';
+        minRecords?: number;
+        sort?: string;
+        limit?: number;
+    };
+    objects: ObjectListItem[];
+    warnings?: string[];
+    metadata?: {
+        duration?: number;
+    };
+};
+/**
+ * Displays contextual next steps based on the objects in the result.
+ * Suggests object describe commands for meaningful objects and
+ * always ends with the definition create command.
+ *
+ * @param log - The logging function
+ * @param objects - The object list items
+ * @param username - The target org username for command examples
+ */
+export declare function displayNextSteps(log: (msg: string) => void, objects: ObjectListItem[], username?: string): void;