chore: code review I

src/Presets.md

@@ -52,9 +52,9 @@ source format
 
 Simple fields (ex: `description`, `userLicense`) remain in the top-level `PO_Manager.permissionset-meta.xml`
 
-Entries not specific to objects remain at the top-level, grouped into files, e.g. `ClassAccess`, `PageAccess`, `UserPermissions`...
+Entries not specific to object's settings remain at the top-level, grouped into files, e.g. `ClassAccess`, `PageAccess`, `UserPermissions`...
 
-Entries specific to objects are grouped in the `objectSettings` directory and grouped into object-specific files, e.g. `PO_Line_Item__c.objectSettings`, in there you'll find entries related to `FieldPermissions`, `TabSettings`, `ObjetPermissions` and other object-specific fields.
+Entries specific to object's settings are grouped in the `objectSettings` directory and grouped into object-specific files, e.g. `PO_Line_Item__c.objectSettings`, in there you'll find entries related to `FieldPermissions`, `TabSettings`, `ObjetPermissions` and other object-specific fields.
 
 ## `decomposeSharingRulesBeta`
 

src/convert/convertContext/decomposedPermissionSetFinalizer.ts

@@ -7,6 +7,7 @@
 import { join } from 'node:path';
 import { ensure, JsonMap } from '@salesforce/ts-types';
 import type { PermissionSet } from '@jsforce/jsforce-node/lib/api/metadata/schema';
+import { SfError } from '@salesforce/core';
 import { MetadataType } from '../../registry';
 import { XML_NS_KEY, XML_NS_URL } from '../../common/constants';
 import { JsToXml } from '../streams';
@@ -21,7 +22,7 @@ type PermissionSetState = {
 };
 
 /**
- * Merges child components that share the same object in the conversion pipeline
+ * Merges child components that share the same related object (/objectSettings/<object name>.objectSettings) in the conversion pipeline
  * into a single file.
  *
  * Inserts unclaimed child components into the parent that belongs to the default package
@@ -41,7 +42,7 @@ export class DecomposedPermissionSetFinalizer extends ConvertTransactionFinalize
       return [];
     }
 
-    const fullName = Array.from(this.transactionState.permissionSetChildByPath.keys())[0].split(':')[1].split('.')[0];
+    const fullName = this.getName();
 
     return [
       {
@@ -61,6 +62,22 @@ export class DecomposedPermissionSetFinalizer extends ConvertTransactionFinalize
       },
     ];
   }
+
+  private getName(): string {
+    let name: string;
+    try {
+      name = Array.from(this.transactionState.permissionSetChildByPath.keys())[0].split(':')[1].split('.')[0];
+    } catch (e) {
+      throw SfError.create({
+        cause: e,
+        message: `unable to parse name between : and . in ${
+          Array.from(this.transactionState.permissionSetChildByPath.keys())[0] ??
+          this.transactionState.permissionSetChildByPath.keys()
+        }`,
+      });
+    }
+    return name;
+  }
 }
 
 /** Return a json object that's built up from the mergeMap children */

src/convert/transformers/decomposedMetadataTransformer.ts

@@ -23,6 +23,7 @@ import type { SourcePath } from '../../common/types';
 import { ComponentSet } from '../../collections/componentSet';
 import type { DecompositionState, DecompositionStateValue } from '../convertContext/decompositionFinalizer';
 import { BaseMetadataTransformer } from './baseMetadataTransformer';
+import type { ComposedMetadata, ComposedMetadataWithChildType, InfoContainer } from './types';
 
 type StateSetter = (forComponent: MetadataComponent, props: Partial<Omit<DecompositionStateValue, 'origin'>>) => void;
 
@@ -286,18 +287,6 @@ export const addChildType = (cm: Required<ComposedMetadata>): ComposedMetadataWi
   throw messages.createError('error_missing_child_type_definition', [cm.parentType.name, cm.childTypeId]);
 };
 
-export type ComposedMetadata = { tagKey: string; tagValue: AnyJson; parentType: MetadataType; childTypeId?: string };
-export type ComposedMetadataWithChildType = ComposedMetadata & { childType: MetadataType };
-
-export type InfoContainer = {
-  entryName: string;
-  childComponent: MetadataComponent;
-  /** the parsed xml */
-  value: JsonMap;
-  parentComponent: SourceComponent;
-  mergeWith?: SourceComponent;
-};
-
 /** returns an data structure with lots of context information in it */
 const toInfoContainer =
   (mergeWith: SourceComponent | undefined) =>

src/convert/transformers/decomposedPermissionSetTransformer.ts

@@ -23,23 +23,28 @@ import type { DecompositionStateValue } from '../convertContext/decompositionFin
 import { BaseMetadataTransformer } from './baseMetadataTransformer';
 import {
   addChildType,
-  ComposedMetadata,
   forceIgnoreAllowsComponent,
   getOutputFile,
   getWriteInfosFromMerge,
   getWriteInfosWithoutMerge,
   hasChildTypeId,
-  InfoContainer,
   setDecomposedState,
   tagToChildTypeId,
 } from './decomposedMetadataTransformer';
+import type { InfoContainer, ComposedMetadata } from './types';
 
 type StateSetter = (forComponent: MetadataComponent, props: Partial<Omit<DecompositionStateValue, 'origin'>>) => void;
 
 Messages.importMessagesDirectory(__dirname);
 const messages = Messages.loadMessages('@salesforce/source-deploy-retrieve', 'sdr');
 
 export class DecomposedPermissionSetTransformer extends BaseMetadataTransformer {
+  /**
+   * Combines a decomposed Permission Set into a singular .permissonset metadata-formatted file
+   *
+   * @param {SourceComponent} component - either the parent or child of a decomposed permission set to be combined with
+   * @returns {Promise<WriteInfo[]>} will be an array with one WriteInfo in it, because they're ending in one file
+   */
   // eslint-disable-next-line @typescript-eslint/require-await
   public async toMetadataFormat(component: SourceComponent): Promise<WriteInfo[]> {
     // only need to do this once
@@ -65,6 +70,14 @@ export class DecomposedPermissionSetTransformer extends BaseMetadataTransformer
     // noop since the finalizer will push the writes to the component writer
     return [];
   }
+
+  /**
+   * will decomopse a .permissionset into a directory containing files, and an 'objectSettings' folder for object-specific settings
+   *
+   * @param {SourceComponent} component A SourceComponent representing a metadata-formatted permission set
+   * @param {SourceComponent | undefined} mergeWith any existing source-formatted permission sets to be merged with, think existing source merging with new information from a retrieve
+   * @returns {Promise<WriteInfo[]>} Will contain file content information, and file paths
+   */
   public async toSourceFormat({ component, mergeWith }: ToSourceFormatInput): Promise<WriteInfo[]> {
     const forceIgnore = component.getForceIgnore();
 
@@ -228,7 +241,7 @@ const getAndCombineChildWriteInfos = (
   return writeInfos;
 };
 
-/** returns a data structure with lots of context information in it */
+/** returns a data structure with lots of context information in it - this is also where the name of the file/component is calculated */
 const toInfoContainer =
   (mergeWith: SourceComponent | undefined) =>
   (parent: SourceComponent) =>

src/convert/transformers/types.ts

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2023, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import { AnyJson, JsonMap } from '@salesforce/ts-types';
+import { MetadataType } from '../../registry';
+import { MetadataComponent, SourceComponent } from '../../resolve';
+
+export type ComposedMetadata = { tagKey: string; tagValue: AnyJson; parentType: MetadataType; childTypeId?: string };
+export type ComposedMetadataWithChildType = ComposedMetadata & { childType: MetadataType };
+
+export type InfoContainer = {
+  entryName: string;
+  childComponent: MetadataComponent;
+  /** the parsed xml */
+  value: JsonMap;
+  parentComponent: SourceComponent;
+  mergeWith?: SourceComponent;
+};