@sentry/wizard 6.11.0 → 6.13.0

package/dist/src/apple/xcode-manager.js

@@ -32,10 +32,70 @@ exports.XcodeProject = void 0;
 const clack = __importStar(require("@clack/prompts"));
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const semver_1 = require("semver");
 const debug_1 = require("../utils/debug");
 const templates = __importStar(require("./templates"));
 const xcode_1 = require("xcode");
 const macos_system_helper_1 = require("./macos-system-helper");
+const XCODE_APPLICATION_PRODUCT_TYPE = 'com.apple.product-type.application';
+const XCODE_UNIT_TEST_PRODUCT_TYPE = 'com.apple.product-type.bundle.unit-test';
+function unquote(value) {
+    return typeof value === 'string' ? value.replace(/"/g, '') : '';
+}
+function stripAppExtension(value) {
+    return value?.endsWith('.app') ? value.slice(0, -'.app'.length) : value;
+}
+function resolveBuildSettingValue(value, targetName) {
+    const resolvedValue = unquote(value)
+        .replace(/\$\(TARGET_NAME\)/g, targetName)
+        .replace(/\$\{TARGET_NAME\}/g, targetName)
+        .trim();
+    return resolvedValue && !resolvedValue.includes('$')
+        ? resolvedValue
+        : undefined;
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter(Boolean))];
+}
+function testHostReferencesApplication(testHost, appHostCandidates) {
+    const resolvedTestHost = unquote(testHost);
+    if (!resolvedTestHost) {
+        return false;
+    }
+    const referencesAppBundle = appHostCandidates.bundleNames.some((bundleName) => containsPathSegment(resolvedTestHost, `${bundleName}.app`));
+    if (!referencesAppBundle) {
+        return false;
+    }
+    return appHostCandidates.executableNames.some((executableName) => containsPathSegment(resolvedTestHost, executableName));
+}
+function containsPathSegment(value, segment) {
+    return new RegExp(`(^|/)${escapeRegExp(segment)}(/|$)`).test(value);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function normalizeSwiftPackageRepositoryURL(value) {
+    return unquote(value).replace(/\/+$/, '');
+}
+function shouldUpdatePackageRequirement(existingRequirement, requestedRequirement) {
+    if (!existingRequirement || typeof existingRequirement !== 'object') {
+        return true;
+    }
+    const requirement = existingRequirement;
+    if (requirement.kind !== requestedRequirement.kind) {
+        return true;
+    }
+    const existingMinimumVersion = requirement.minimumVersion;
+    if (typeof existingMinimumVersion !== 'string') {
+        return true;
+    }
+    const existingVersion = (0, semver_1.valid)(existingMinimumVersion);
+    const requestedVersion = (0, semver_1.valid)(requestedRequirement.minimumVersion);
+    if (!existingVersion || !requestedVersion) {
+        return existingMinimumVersion !== requestedRequirement.minimumVersion;
+    }
+    return (0, semver_1.lt)(existingVersion, requestedVersion);
+}
 function setDebugInformationFormatAndSandbox(proj, targetName) {
     const xcObjects = proj.hash.project.objects;
     if (!xcObjects.PBXNativeTarget) {
@@ -70,106 +130,6 @@ function setDebugInformationFormatAndSandbox(proj, targetName) {
         xcObjects.XCBuildConfiguration[buildListConfigId.value] = config;
     }
 }
-function addSentrySPM(proj, targetName) {
-    const xcObjects = proj.hash.project.objects;
-    const sentryFrameworkUUID = proj.generateUuid();
-    const sentrySPMUUID = proj.generateUuid();
-    // Check whether xcObjects already have sentry framework
-    if (xcObjects.PBXFrameworksBuildPhase) {
-        for (const key in xcObjects.PBXFrameworksBuildPhase || {}) {
-            const frameworkBuildPhase = xcObjects.PBXFrameworksBuildPhase[key];
-            if (key.endsWith('_comment') || typeof frameworkBuildPhase === 'string') {
-                // Ignore comments
-                continue;
-            }
-            for (const framework of frameworkBuildPhase.files ?? []) {
-                // We identify the Sentry framework by the comment "Sentry in Frameworks",
-                // which is set by this manager in previous runs.
-                if (framework.comment === 'Sentry in Frameworks') {
-                    return;
-                }
-            }
-        }
-    }
-    if (!xcObjects.PBXBuildFile) {
-        xcObjects.PBXBuildFile = {};
-    }
-    xcObjects.PBXBuildFile[sentryFrameworkUUID] = {
-        isa: 'PBXBuildFile',
-        productRef: sentrySPMUUID,
-        productRef_comment: 'Sentry',
-    };
-    xcObjects.PBXBuildFile[`${sentryFrameworkUUID}_comment`] =
-        'Sentry in Frameworks';
-    if (!xcObjects.PBXFrameworksBuildPhase) {
-        xcObjects.PBXFrameworksBuildPhase = {};
-    }
-    for (const key in xcObjects.PBXFrameworksBuildPhase) {
-        const value = xcObjects.PBXFrameworksBuildPhase[key];
-        if (key.endsWith('_comment') || typeof value === 'string') {
-            // Ignore comments
-            continue;
-        }
-        const frameworks = value.files ?? [];
-        frameworks.push({
-            value: sentryFrameworkUUID,
-            comment: 'Sentry in Frameworks',
-        });
-        value.files = frameworks;
-        xcObjects.PBXFrameworksBuildPhase[key] = value;
-    }
-    if (!xcObjects.PBXNativeTarget) {
-        xcObjects.PBXNativeTarget = {};
-    }
-    const targetKey = Object.keys(xcObjects.PBXNativeTarget || {}).filter((key) => {
-        const value = xcObjects.PBXNativeTarget?.[key];
-        return (!key.endsWith('_comment') &&
-            typeof value !== 'string' &&
-            value?.name === targetName);
-    })[0];
-    const target = xcObjects.PBXNativeTarget[targetKey];
-    if (!target.packageProductDependencies) {
-        target.packageProductDependencies = [];
-    }
-    target.packageProductDependencies.push({
-        value: sentrySPMUUID,
-        comment: 'Sentry',
-    });
-    const sentrySwiftPackageUUID = proj.generateUuid();
-    const xcProject = proj.getFirstProject().firstProject;
-    if (!xcProject.packageReferences) {
-        xcProject.packageReferences = [];
-    }
-    xcProject.packageReferences.push({
-        value: sentrySwiftPackageUUID,
-        comment: 'XCRemoteSwiftPackageReference "sentry-cocoa"',
-    });
-    if (!xcObjects.XCRemoteSwiftPackageReference) {
-        xcObjects.XCRemoteSwiftPackageReference = {};
-    }
-    xcObjects.XCRemoteSwiftPackageReference[sentrySwiftPackageUUID] = {
-        isa: 'XCRemoteSwiftPackageReference',
-        repositoryURL: '"https://github.com/getsentry/sentry-cocoa/"',
-        requirement: {
-            kind: 'upToNextMajorVersion',
-            minimumVersion: '8.0.0',
-        },
-    };
-    xcObjects.XCRemoteSwiftPackageReference[`${sentrySwiftPackageUUID}_comment`] =
-        'XCRemoteSwiftPackageReference "sentry-cocoa"';
-    if (!xcObjects.XCSwiftPackageProductDependency) {
-        xcObjects.XCSwiftPackageProductDependency = {};
-    }
-    xcObjects.XCSwiftPackageProductDependency[sentrySPMUUID] = {
-        isa: 'XCSwiftPackageProductDependency',
-        package: sentrySwiftPackageUUID,
-        package_comment: 'XCRemoteSwiftPackageReference "sentry-cocoa"',
-        productName: 'Sentry',
-    };
-    xcObjects.XCSwiftPackageProductDependency[`${sentrySPMUUID}_comment`] =
-        'Sentry';
-    clack.log.step('Added Sentry SPM dependency to your project');
-}
 class XcodeProject {
     /**
      * The directory where the Xcode project is located.
@@ -208,13 +168,110 @@ class XcodeProject {
             const value = targets[key];
             return (!key.endsWith('_comment') &&
                 typeof value !== 'string' &&
-                value.productType.startsWith('"com.apple.product-type.application'));
+                unquote(value.productType).startsWith(XCODE_APPLICATION_PRODUCT_TYPE));
+        })
+            .map((key) => {
+            return targets[key].name;
+        });
+    }
+    getUnitTestTargetNames() {
+        const targets = this.objects.PBXNativeTarget ?? {};
+        return Object.keys(targets)
+            .filter((key) => {
+            const value = targets[key];
+            return this.isUnitTestTargetEntry(key, value);
         })
             .map((key) => {
             return targets[key].name;
         });
     }
-    updateXcodeProject(sentryProject, target, addSPMReference, uploadSource = true) {
+    getHostedUnitTestTargetNames() {
+        const targets = this.objects.PBXNativeTarget ?? {};
+        return Object.keys(targets)
+            .filter((key) => {
+            const value = targets[key];
+            return (this.isUnitTestTargetEntry(key, value) &&
+                this.getTargetBuildSettings(value).some((buildSettings) => Boolean(unquote(buildSettings.TEST_HOST).trim())));
+        })
+            .map((key) => {
+            return targets[key].name;
+        });
+    }
+    getHostedUnitTestTargetNamesForApplicationTarget(appTargetName) {
+        const appTarget = this.findNativeTargetByName(appTargetName);
+        if (!appTarget) {
+            return [];
+        }
+        const appHostCandidates = this.getApplicationHostCandidates(appTarget);
+        const targets = this.objects.PBXNativeTarget ?? {};
+        return Object.keys(targets)
+            .filter((key) => {
+            const value = targets[key];
+            return (!key.endsWith('_comment') &&
+                typeof value !== 'string' &&
+                unquote(value.productType) === XCODE_UNIT_TEST_PRODUCT_TYPE &&
+                this.getTargetBuildSettings(value).some((buildSettings) => testHostReferencesApplication(buildSettings.TEST_HOST, appHostCandidates)));
+        })
+            .map((key) => {
+            return targets[key].name;
+        });
+    }
+    getBundleIdentifierForTarget(targetName) {
+        const target = this.findNativeTargetByName(targetName);
+        if (!target) {
+            return undefined;
+        }
+        return this.getTargetBuildSettings(target.obj)
+            .map((buildSettings) => {
+            return unquote(buildSettings.PRODUCT_BUNDLE_IDENTIFIER);
+        })
+            .find(Boolean);
+    }
+    /**
+     * Idempotently links a Swift package product to one target dependency list
+     * and Frameworks build phase. Returns whether the pbxproj graph changed and
+     * whether the product is linked after the operation.
+     */
+    ensureSwiftPackageProductLinked(targetName, product) {
+        const target = this.findNativeTargetByName(targetName);
+        if (!target) {
+            (0, debug_1.debug)(`Target not found: ${targetName}`);
+            return { changed: false, linked: false };
+        }
+        const frameworksBuildPhase = this.findFrameworksBuildPhaseInTarget(target.obj);
+        if (!frameworksBuildPhase) {
+            (0, debug_1.debug)(`Frameworks build phase not found for target: ${targetName}`);
+            return { changed: false, linked: false };
+        }
+        let changed = false;
+        // Ensure the remote Swift package object exists.
+        const packageReference = this.ensureSwiftPackageReference(product.package);
+        changed = packageReference.changed || changed;
+        // Attach the Swift package object to the root Xcode project.
+        changed =
+            this.ensureProjectSwiftPackageReference(packageReference.packageRefId, product.package.commentName) || changed;
+        // Ensure the package product dependency object exists.
+        const productDependency = this.ensureSwiftPackageProductDependency(packageReference.packageRefId, product);
+        changed = productDependency.changed || changed;
+        if (!target.obj.packageProductDependencies) {
+            target.obj.packageProductDependencies = [];
+        }
+        // Attach the package product dependency to the selected target.
+        if (!target.obj.packageProductDependencies.some((dependency) => {
+            return dependency.value === productDependency.productDependencyId;
+        })) {
+            target.obj.packageProductDependencies.push({
+                value: productDependency.productDependencyId,
+                comment: product.productName,
+            });
+            changed = true;
+        }
+        // Link the package product in the target Frameworks build phase.
+        changed =
+            this.ensureFrameworksBuildFile(frameworksBuildPhase, productDependency.productDependencyId, product) || changed;
+        return { changed, linked: true };
+    }
+    updateXcodeProject(sentryProject, target, swiftPackageProduct, uploadSource = true) {
         this.addUploadSymbolsScript({
             sentryProject,
             targetName: target,
@@ -223,11 +280,15 @@ class XcodeProject {
         if (uploadSource) {
             setDebugInformationFormatAndSandbox(this.project, target);
         }
-        if (addSPMReference) {
-            addSentrySPM(this.project, target);
+        if (swiftPackageProduct &&
+            !(swiftPackageProduct.existingFrameworkComment &&
+                this.hasFrameworkBuildFileCommentInTarget(target, swiftPackageProduct.existingFrameworkComment))) {
+            const result = this.ensureSwiftPackageProductLinked(target, swiftPackageProduct.product);
+            if (result.changed && swiftPackageProduct.successMessage) {
+                clack.log.step(swiftPackageProduct.successMessage);
+            }
         }
-        const newContent = this.project.writeSync();
-        fs.writeFileSync(this.pbxprojPath, newContent);
+        this.write();
     }
     addUploadSymbolsScript({ sentryProject, targetName, uploadSource, }) {
         const xcObjects = this.project.hash.project.objects;
@@ -306,6 +367,87 @@ class XcodeProject {
             clack.log.step(`Added Sentry upload script to "${targetName}" build phase`);
         }
     }
+    write() {
+        const newContent = this.project.writeSync();
+        fs.writeFileSync(this.pbxprojPath, newContent);
+    }
+    getSynchronizedRootGroupPathsForTarget(targetName) {
+        const nativeTarget = this.findNativeTargetByName(targetName);
+        if (!nativeTarget) {
+            return [];
+        }
+        return (nativeTarget.obj.fileSystemSynchronizedGroups ?? []).reduce((groupPaths, group) => {
+            const groupObj = this.objects.PBXFileSystemSynchronizedRootGroup?.[group.value];
+            if (!groupObj || typeof groupObj !== 'object') {
+                return groupPaths;
+            }
+            const groupPath = this.resolveAbsolutePathOfSynchronizedRootGroup({
+                id: group.value,
+                obj: groupObj,
+            });
+            if (!groupPath) {
+                return groupPaths;
+            }
+            return groupPaths.concat(groupPath);
+        }, new Array());
+    }
+    /**
+     * Ensures a Swift file is compiled by a target, either through an Xcode
+     * synchronized root group or an explicit Sources build phase entry.
+     */
+    addSwiftSourceFileToTarget(args) {
+        const nativeTarget = this.findNativeTargetByName(args.targetName);
+        const defaultResult = { changed: false, included: false };
+        if (!nativeTarget) {
+            (0, debug_1.debug)(`Target not found: ${args.targetName}`);
+            return defaultResult;
+        }
+        const absoluteFilePath = args.filePath;
+        if (this.isFileIncludedBySynchronizedRootGroup(nativeTarget, absoluteFilePath)) {
+            return {
+                changed: false,
+                included: true,
+            };
+        }
+        const sourceBuildPhase = this.findSourceBuildPhaseInTarget(nativeTarget.obj);
+        if (!sourceBuildPhase) {
+            (0, debug_1.debug)(`Sources build phase not found for target: ${args.targetName}`);
+            return defaultResult;
+        }
+        const fileReference = this.ensureSwiftFileReference(absoluteFilePath);
+        const sourceBuildPhaseFiles = sourceBuildPhase.obj.files ?? [];
+        const existingBuildFileReference = sourceBuildPhaseFiles.find((file) => {
+            const buildFile = this.objects.PBXBuildFile?.[file.value];
+            return (buildFile &&
+                typeof buildFile !== 'string' &&
+                buildFile.fileRef === fileReference.fileReferenceId);
+        });
+        if (existingBuildFileReference) {
+            return {
+                changed: fileReference.changed,
+                included: true,
+            };
+        }
+        if (!this.objects.PBXBuildFile) {
+            this.objects.PBXBuildFile = {};
+        }
+        const buildFileId = this.project.generateUuid();
+        const fileName = path.basename(absoluteFilePath);
+        this.objects.PBXBuildFile[buildFileId] = {
+            isa: 'PBXBuildFile',
+            fileRef: fileReference.fileReferenceId,
+            fileRef_comment: fileName,
+        };
+        this.objects.PBXBuildFile[`${buildFileId}_comment`] = `${fileName} in Sources`;
+        sourceBuildPhase.obj.files = [
+            ...sourceBuildPhaseFiles,
+            {
+                value: buildFileId,
+                comment: `${fileName} in Sources`,
+            },
+        ];
+        return { changed: true, included: true };
+    }
     /**
      * Retrieves all source files associated with a specific target in the Xcode project.
      * This is used to find files where we can inject Sentry initialization code.
@@ -343,6 +485,265 @@ class XcodeProject {
         (0, debug_1.debug)(`Found ${filesInSynchronizedRootGroups.length} files in synchronized root groups for target: ${targetName}`);
         return [...filesInBuildPhase, ...filesInSynchronizedRootGroups];
     }
+    isUnitTestTargetEntry(key, value) {
+        return (!key.endsWith('_comment') &&
+            typeof value !== 'string' &&
+            value !== undefined &&
+            unquote(value.productType) === XCODE_UNIT_TEST_PRODUCT_TYPE);
+    }
+    getTargetBuildSettings(target) {
+        const buildConfigurationListId = target.buildConfigurationList;
+        if (!buildConfigurationListId) {
+            return [];
+        }
+        const configurationList = this.objects.XCConfigurationList?.[buildConfigurationListId];
+        if (!configurationList || typeof configurationList === 'string') {
+            return [];
+        }
+        return (configurationList.buildConfigurations ?? []).reduce((buildSettings, buildConfiguration) => {
+            const configuration = this.objects.XCBuildConfiguration?.[buildConfiguration.value];
+            if (!configuration || typeof configuration === 'string') {
+                return buildSettings;
+            }
+            return buildSettings.concat(configuration.buildSettings ?? {});
+        }, new Array());
+    }
+    getApplicationHostCandidates(target) {
+        const buildSettings = this.getTargetBuildSettings(target.obj);
+        const productReferencePath = this.getProductReferencePath(target.obj);
+        const productReferenceName = stripAppExtension(productReferencePath);
+        const targetProductName = resolveBuildSettingValue(target.obj.productName, target.obj.name);
+        const buildSettingProductNames = buildSettings.flatMap((settings) => [
+            resolveBuildSettingValue(settings.PRODUCT_NAME, target.obj.name),
+            stripAppExtension(resolveBuildSettingValue(settings.FULL_PRODUCT_NAME, target.obj.name)),
+            stripAppExtension(resolveBuildSettingValue(settings.WRAPPER_NAME, target.obj.name)),
+        ]);
+        const buildSettingExecutableNames = buildSettings.map((settings) => resolveBuildSettingValue(settings.EXECUTABLE_NAME, target.obj.name));
+        return {
+            bundleNames: uniqueStrings([
+                target.obj.name,
+                targetProductName,
+                productReferenceName,
+                ...buildSettingProductNames,
+            ]),
+            executableNames: uniqueStrings([
+                target.obj.name,
+                targetProductName,
+                productReferenceName,
+                ...buildSettingExecutableNames,
+            ]),
+        };
+    }
+    getProductReferencePath(target) {
+        if (!target.productReference) {
+            return undefined;
+        }
+        const productReference = this.objects.PBXFileReference?.[target.productReference];
+        if (!productReference || typeof productReference === 'string') {
+            return undefined;
+        }
+        return unquote(productReference.path);
+    }
+    hasFrameworkBuildFileCommentInTarget(targetName, comment) {
+        const target = this.findNativeTargetByName(targetName);
+        if (!target) {
+            return false;
+        }
+        const frameworksBuildPhase = this.findFrameworksBuildPhaseInTarget(target.obj);
+        return (frameworksBuildPhase?.files ?? []).some((framework) => {
+            return framework.comment === comment;
+        });
+    }
+    ensureSwiftPackageReference(packageSpec) {
+        if (!this.objects.XCRemoteSwiftPackageReference) {
+            this.objects.XCRemoteSwiftPackageReference = {};
+        }
+        const packageReferences = this.objects
+            .XCRemoteSwiftPackageReference;
+        const requestedRepositoryURL = normalizeSwiftPackageRepositoryURL(packageSpec.repositoryURL);
+        const existingPackageReference = Object.entries(packageReferences).find(([id, value]) => {
+            if (id.endsWith('_comment') || typeof value !== 'object') {
+                return false;
+            }
+            const packageReference = value;
+            return (normalizeSwiftPackageRepositoryURL(packageReference.repositoryURL) ===
+                requestedRepositoryURL);
+        });
+        if (existingPackageReference) {
+            const packageReference = existingPackageReference[1];
+            if (shouldUpdatePackageRequirement(packageReference.requirement, packageSpec.requirement)) {
+                packageReference.requirement = packageSpec.requirement;
+                return { packageRefId: existingPackageReference[0], changed: true };
+            }
+            return { packageRefId: existingPackageReference[0], changed: false };
+        }
+        const packageRefId = this.project.generateUuid();
+        packageReferences[packageRefId] = {
+            isa: 'XCRemoteSwiftPackageReference',
+            repositoryURL: `"${packageSpec.repositoryURL}"`,
+            requirement: packageSpec.requirement,
+        };
+        packageReferences[`${packageRefId}_comment`] =
+            this.swiftPackageReferenceComment(packageSpec.commentName);
+        return { packageRefId, changed: true };
+    }
+    ensureProjectSwiftPackageReference(packageRefId, commentName) {
+        const xcodeProject = this.project.getFirstProject().firstProject;
+        if (!xcodeProject.packageReferences) {
+            xcodeProject.packageReferences = [];
+        }
+        if (xcodeProject.packageReferences.some((packageReference) => {
+            return packageReference.value === packageRefId;
+        })) {
+            return false;
+        }
+        xcodeProject.packageReferences.push({
+            value: packageRefId,
+            comment: this.swiftPackageReferenceComment(commentName),
+        });
+        return true;
+    }
+    ensureSwiftPackageProductDependency(packageRefId, product) {
+        if (!this.objects.XCSwiftPackageProductDependency) {
+            this.objects.XCSwiftPackageProductDependency = {};
+        }
+        const productDependencies = this.objects
+            .XCSwiftPackageProductDependency;
+        const existingProductDependency = Object.entries(productDependencies).find(([id, value]) => {
+            if (id.endsWith('_comment') || typeof value !== 'object') {
+                return false;
+            }
+            const productDependency = value;
+            return (productDependency.package === packageRefId &&
+                unquote(productDependency.productName) === product.productName);
+        });
+        if (existingProductDependency) {
+            return {
+                productDependencyId: existingProductDependency[0],
+                changed: false,
+            };
+        }
+        const productDependencyId = this.project.generateUuid();
+        productDependencies[productDependencyId] = {
+            isa: 'XCSwiftPackageProductDependency',
+            package: packageRefId,
+            package_comment: this.swiftPackageReferenceComment(product.package.commentName),
+            productName: product.productName,
+        };
+        productDependencies[`${productDependencyId}_comment`] = product.productName;
+        return { productDependencyId, changed: true };
+    }
+    ensureFrameworksBuildFile(frameworksBuildPhase, productDependencyId, product) {
+        if (!this.objects.PBXBuildFile) {
+            this.objects.PBXBuildFile = {};
+        }
+        const existingFrameworkEntry = (frameworksBuildPhase.files ?? []).find((framework) => {
+            const buildFile = this.objects.PBXBuildFile?.[framework.value];
+            return (buildFile &&
+                typeof buildFile !== 'string' &&
+                buildFile.productRef === productDependencyId);
+        });
+        if (existingFrameworkEntry) {
+            return false;
+        }
+        const buildFileId = this.project.generateUuid();
+        this.objects.PBXBuildFile[buildFileId] = {
+            isa: 'PBXBuildFile',
+            productRef: productDependencyId,
+            productRef_comment: product.productName,
+        };
+        this.objects.PBXBuildFile[`${buildFileId}_comment`] = `${product.productName} in Frameworks`;
+        if (!frameworksBuildPhase.files) {
+            frameworksBuildPhase.files = [];
+        }
+        frameworksBuildPhase.files.push({
+            value: buildFileId,
+            comment: `${product.productName} in Frameworks`,
+        });
+        return true;
+    }
+    findFrameworksBuildPhaseInTarget(target) {
+        for (const buildPhaseReference of target.buildPhases ?? []) {
+            const buildPhase = this.objects.PBXFrameworksBuildPhase?.[buildPhaseReference.value];
+            if (buildPhase && typeof buildPhase !== 'string') {
+                return buildPhase;
+            }
+        }
+        return undefined;
+    }
+    swiftPackageReferenceComment(commentName) {
+        return `XCRemoteSwiftPackageReference "${commentName}"`;
+    }
+    isFileIncludedBySynchronizedRootGroup(nativeTarget, absoluteFilePath) {
+        return this.findFilesInSynchronizedRootGroups(nativeTarget).some((filePath) => filePath === absoluteFilePath);
+    }
+    ensureSwiftFileReference(absoluteFilePath) {
+        if (!this.objects.PBXFileReference) {
+            this.objects.PBXFileReference = {};
+        }
+        const existingFileReference = Object.entries(this.objects.PBXFileReference).find(([id, fileReference]) => {
+            if (id.endsWith('_comment') || typeof fileReference !== 'object') {
+                return false;
+            }
+            const resolvedFilePath = this.resolveAbsolutePathOfFileReference({
+                id,
+                obj: fileReference,
+            });
+            return resolvedFilePath === absoluteFilePath;
+        });
+        if (existingFileReference) {
+            return { fileReferenceId: existingFileReference[0], changed: false };
+        }
+        const fileReferenceId = this.project.generateUuid();
+        const fileName = path.basename(absoluteFilePath);
+        const relativePath = path.relative(this.baseDir, absoluteFilePath);
+        this.objects.PBXFileReference[fileReferenceId] = {
+            isa: 'PBXFileReference',
+            lastKnownFileType: 'sourcecode.swift',
+            path: relativePath,
+            sourceTree: 'SOURCE_ROOT',
+        };
+        this.objects.PBXFileReference[`${fileReferenceId}_comment`] = fileName;
+        this.addFileReferenceToBestGroup(fileReferenceId, fileName, absoluteFilePath);
+        return { fileReferenceId, changed: true };
+    }
+    addFileReferenceToBestGroup(fileReferenceId, fileName, absoluteFilePath) {
+        const parentDirectory = path.dirname(absoluteFilePath);
+        const parentGroup = this.groups.find((group) => {
+            const groupPath = this.resolveAbsolutePathOfGroup(group);
+            return groupPath === parentDirectory;
+        }) ?? this.mainGroup;
+        if (!parentGroup) {
+            return;
+        }
+        if (!parentGroup.obj.children) {
+            parentGroup.obj.children = [];
+        }
+        if (parentGroup.obj.children.some((child) => child.value === fileReferenceId)) {
+            return;
+        }
+        parentGroup.obj.children.push({
+            value: fileReferenceId,
+            comment: fileName,
+        });
+    }
+    get mainGroup() {
+        const project = Object.entries(this.objects.PBXProject ?? {}).find(([id, candidate]) => {
+            return !id.endsWith('_comment') && typeof candidate === 'object';
+        })?.[1];
+        if (!project || typeof project !== 'object') {
+            return undefined;
+        }
+        const mainGroupId = project.mainGroup;
+        if (!mainGroupId) {
+            return undefined;
+        }
+        const mainGroup = this.objects.PBXGroup?.[mainGroupId];
+        if (!mainGroup || typeof mainGroup !== 'object') {
+            return undefined;
+        }
+        return { id: mainGroupId, obj: mainGroup };
+    }
     // ================================ TARGET HELPERS ================================
     /**
      * Finds a native target by name.