rork-xcode 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -10,33 +10,34 @@
  * - `( item, item, ... )` parses to a {@link PbxprojArray}.
  * - `<48656c6c6f>` data runs parse to `Uint8Array`.
  * - Unquoted integers and decimals (`46`, `3.14`, `-12`) parse to `number`
- *   under one print-back rule: the literal converts exactly when the number
- *   formats back to the identical text.
+ *   under one print-back rule, where the literal converts exactly when the
+ *   number formats back to the identical text.
  * - Everything else (quoted text, identifiers, uuids, paths) parses to
  *   `string`.
  *
- * The print-back rule is what keeps round-trips faithful: any literal the
+ * The print-back rule is what keeps round-trips faithful. Any literal the
  * conversion would reshape stays a string, so serializing never changes a
  * scalar's bytes. Leading-zero runs like `0755` would corrupt file modes,
- * trailing-zero decimals like `5.0` would drop the zero build settings are
- * written with, bare-dot decimals like `.5` would grow a leading zero, and
+ * trailing-zero decimals like `5.0` would drop the zero that build
+ * settings are written with, bare-dot decimals like `.5` would grow a
+ * leading zero, and
  * digit runs beyond `Number.MAX_SAFE_INTEGER` would lose precision (a
- * 24-character identifier can be all digits); all of these therefore parse
- * as strings.
+ * 24-character identifier can be all digits), so all of these parse as
+ * strings.
  *
  * @module
  */
 /**
  * A value representable in a `project.pbxproj` document.
  *
- * Notably absent are booleans and null: the format has no notation for
+ * Notably absent are booleans and null. The format has no notation for
  * either, and Xcode models flags as the strings `"YES"` and `"NO"`.
  */
 type PbxprojValue = string | number | Uint8Array | PbxprojArray | PbxprojObject;
 /**
  * A `( ... )` list: an ordered array of values.
  *
- * This is a plain JavaScript array; the interface exists only to give the
+ * This is a plain JavaScript array. The interface exists only to give the
  * recursive {@link PbxprojValue} type a name.
  */
 interface PbxprojArray extends Array<PbxprojValue> {}
@@ -55,18 +56,18 @@ interface PbxprojObject {
 /**
  * Serializes a project document to `project.pbxproj` text.
  *
- * The input is the same shape {@link parsePbxproj} produces; see the module
- * documentation of `types.ts` for the value model. Output is stable: two
+ * The input is the same shape {@link parsePbxproj} produces. See the module
+ * documentation of `types.ts` for the value model. Output is stable, so two
  * calls with semantically equal documents produce identical text, and the
  * layout matches what Xcode itself writes so diffs stay minimal.
  *
  * @param root The document root. Real project documents carry `objects`,
  *   `rootObject`, and the version fields, but any dictionary serializes.
  * @returns The document text, terminated by a newline.
- * @throws PbxprojBuildError when a value has no pbxproj representation:
- *   `null`, `undefined`, booleans, bigints, functions, symbols, class
- *   instances, or non-finite numbers. The error names the path of the
- *   offending value.
+ * @throws PbxprojBuildError when a value has no pbxproj representation,
+ *   meaning `null`, `undefined`, booleans, bigints, functions, symbols,
+ *   class instances, or non-finite numbers. The error names the path of
+ *   the offending value.
  */
 declare function buildPbxproj(root: PbxprojObject): string;
 //#endregion
@@ -107,7 +108,7 @@ declare class PbxprojParseError extends Error {
   /** Where in the source text parsing failed. */
   readonly position: PbxprojErrorPosition;
   /**
-   * @param message Failure description without location; the location is
+   * @param message Failure description without location. The location is
    *   appended automatically.
    * @param source Full source text, used to compute the position.
    * @param offset Character offset of the failure inside `source`.
@@ -126,7 +127,26 @@ declare class XcschemeParseError extends Error {
   /** Where in the source text parsing failed. */
   readonly position: PbxprojErrorPosition;
   /**
-   * @param message Failure description without location; the location is
+   * @param message Failure description without location. The location is
+   *   appended automatically.
+   * @param source Full source text, used to compute the position.
+   * @param offset Character offset of the failure inside `source`.
+   */
+  constructor(message: string, source: string, offset: number);
+}
+/**
+ * Thrown when the source text is not a well-formed build configuration
+ * file (the line-based format of `.xcconfig` files).
+ *
+ * The message always embeds the line and column of the failure, and the
+ * same information is available in structured form on {@link position}
+ * for programmatic use.
+ */
+declare class XcconfigParseError extends Error {
+  /** Where in the source text parsing failed. */
+  readonly position: PbxprojErrorPosition;
+  /**
+   * @param message Failure description without location. The location is
    *   appended automatically.
    * @param source Full source text, used to compute the position.
    * @param offset Character offset of the failure inside `source`.
@@ -144,14 +164,14 @@ declare class XcschemeBuildError extends Error {
   /** Path to the offending element from the root, e.g. `Scheme.BuildAction[0]`. */
   readonly path: string;
   /**
-   * @param message Failure description without location; the element path
+   * @param message Failure description without location. The element path
    *   is appended automatically.
    * @param path Path to the offending element from the root.
    */
   constructor(message: string, path: string);
 }
 /**
- * Thrown by the object model when an operation cannot proceed: the
+ * Thrown by the object model when an operation cannot proceed, because the
  * document lacks the structure the operation needs (no objects dictionary,
  * no root project object), a view's object was removed from the document,
  * or a creation request names a product type the model cannot scaffold.
@@ -180,7 +200,7 @@ declare class PbxprojBuildError extends Error {
   /** Path to the offending value from the root, e.g. `$.objects.13B07F86.name`. */
   readonly path: string;
   /**
-   * @param message Failure description without location; the value path is
+   * @param message Failure description without location. The value path is
    *   appended automatically.
    * @param path Path to the offending value from the root, `$`.
    */
@@ -191,15 +211,15 @@ declare class PbxprojBuildError extends Error {
 /**
  * Names and well-known values of the pbxproj object vocabulary.
  *
- * Everything here mirrors strings Xcode itself writes; nothing is invented.
- * Centralizing them keeps the object model free of string literals and
- * gives call sites one place to import from.
+ * Everything here mirrors strings Xcode itself writes, and nothing is
+ * invented. Centralizing them keeps the object model free of string
+ * literals and gives call sites one place to import from.
  *
  * @module
  */
 /**
  * The `isa` names the object model works with. The parser and serializer
- * accept any isa; this list only covers the kinds the model creates or
+ * accept any isa, and this list only covers the kinds the model creates or
  * gives typed access to.
  */
 declare const Isa: {
@@ -608,8 +628,13 @@ declare class Target<Properties extends TargetProperties = TargetProperties> ext
    * generated app templates set values like `SDKROOT` only at the project
    * level.
    *
-   * Only string values are returned; a list- or number-valued setting reads
-   * as `undefined`.
+   * Configurations based on `.xcconfig` files take part once the files
+   * are registered through {@link XcodeProject.registerXcconfig}, in
+   * Xcode's order of target settings, then the target's xcconfig, then
+   * project settings, then the project's xcconfig.
+   *
+   * Only string values are returned, so a list- or number-valued setting
+   * reads as `undefined`.
    */
   getBuildSetting(key: string): string | undefined;
   /**
@@ -855,7 +880,7 @@ declare class Group<Properties extends GroupProperties = GroupProperties> extend
    * it to the group's children.
    *
    * The reference's `lastKnownFileType` derives from the file extension
-   * when it is a known kind; otherwise the reference carries no type and
+   * when it is a known kind. Otherwise the reference carries no type and
    * Xcode re-derives one on open.
    *
    * @param path File path relative to the group, for example
@@ -881,8 +906,8 @@ declare class VariantGroup extends Group {
 declare class BuildPhase<Properties extends BuildPhaseProperties = BuildPhaseProperties> extends XcodeObject<Properties> {
   /**
    * The phase's display name, when it carries an explicit one. Xcode names
-   * copy-files and shell-script phases; the standard phases derive their
-   * names from their isa.
+   * copy-files and shell-script phases, while the standard phases derive
+   * their names from their isa.
    */
   get name(): string | undefined;
   /**
@@ -910,7 +935,7 @@ declare class BuildPhase<Properties extends BuildPhaseProperties = BuildPhasePro
    * @param reference The file reference or package product the build file
    *   should point at.
    * @param options.referenceKey Which build-file field carries the
-   *   reference: `fileRef` for file references (the default) or
+   *   reference, either `fileRef` for file references (the default) or
    *   `productRef` for Swift package products.
    * @param options.settings Optional per-file settings, for example
    *   `{ ATTRIBUTES: ["RemoveHeadersOnCopy"] }`.
@@ -1005,7 +1030,7 @@ declare class BuildFile extends XcodeObject<BuildFileProperties> {
   /**
    * The view of the file reference the build file points at, when it
    * points at one. Build files for Swift package products carry a
-   * `productRef` instead; see {@link productDependency}.
+   * `productRef` instead, resolved through {@link productDependency}.
    */
   fileReference(): XcodeObject | undefined;
   /**
@@ -1031,12 +1056,12 @@ declare class SyncRootGroup extends XcodeObject<SyncRootGroupProperties> {
    *
    * Xcode keeps one exception set per target and folder, so when this
    * group already carries a set for the target, the file names merge into
-   * it instead of creating a second set; names already excluded are not
-   * duplicated.
+   * it instead of creating a second set, and names already excluded are
+   * not duplicated.
    *
    * The standard use is keeping a scaffolded `Info.plist` from being
-   * double-copied: the build already processes it through the target's
-   * `INFOPLIST_FILE` setting.
+   * double-copied, since the build already processes it through the
+   * target's `INFOPLIST_FILE` setting.
    *
    * @param target The target whose membership the exceptions restrict.
    * @param membershipExceptions File names inside the folder to exclude.
@@ -1128,6 +1153,13 @@ declare class BuildConfiguration extends XcodeObject<BuildConfigurationPropertie
    * document.
    */
   get buildSettings(): BuildSettings | undefined;
+  /**
+   * The view of the `.xcconfig` file reference this configuration is
+   * based on, when the configuration has one and it resolves. The file's
+   * settings sit below the configuration's own `buildSettings` in
+   * Xcode's resolution order.
+   */
+  baseConfigurationReference(): FileReference | undefined;
 }
 /**
  * A `PBXBuildStyle` is the pre-Xcode-2 predecessor of
@@ -1270,6 +1302,227 @@ declare class ReferenceProxy extends XcodeObject<ReferenceProxyProperties> {
   remoteReference(): ContainerItemProxy | undefined;
 }
 //#endregion
+//#region src/xcconfig/types.d.ts
+/**
+ * Document types for Xcode build configuration files (`.xcconfig`).
+ *
+ * The format is line based, so the document is the ordered list of parsed
+ * lines. Every statement keeps the exact text it was parsed from (`raw`)
+ * and its line terminator (`eol`), which is what lets an untouched
+ * document rebuild byte for byte even though the format is hand-authored
+ * and has no canonical layout.
+ *
+ * @module
+ */
+/**
+ * One `[name=value]` condition attached to a setting assignment, as in
+ * `LDFLAGS[sdk=iphoneos*] = -lfoo`.
+ */
+interface XcconfigCondition {
+  /** The condition name, for example `sdk`, `arch`, or `config`. */
+  name: string;
+  /** The condition value, which may carry a trailing `*` wildcard. */
+  value: string;
+}
+/**
+ * A `KEY = value` line, optionally with conditions between the key and
+ * the equals sign. The value has surrounding whitespace, an optional
+ * trailing semicolon, and any trailing `//` comment removed.
+ */
+interface XcconfigAssignment {
+  kind: "assignment";
+  /** The setting name. */
+  key: string;
+  /** The `[name=value]` conditions, in written order. Usually empty. */
+  conditions: readonly XcconfigCondition[];
+  /** The assigned value with comment, semicolon, and padding stripped. */
+  value: string;
+  /** The exact source line, without its terminator. */
+  raw: string;
+  /** The line terminator, `"\n"`, `"\r\n"`, or `""` on a final line. */
+  eol: string;
+}
+/**
+ * An `#include "path"` line. The optional form `#include? "path"` tells
+ * Xcode to ignore a missing file, and callers should mirror that when
+ * resolving includes.
+ */
+interface XcconfigInclude {
+  kind: "include";
+  /** The include path exactly as written between the quotes. */
+  path: string;
+  /** True for the `#include?` form. */
+  optional: boolean;
+  /** The exact source line, without its terminator. */
+  raw: string;
+  /** The line terminator, `"\n"`, `"\r\n"`, or `""` on a final line. */
+  eol: string;
+}
+/**
+ * A line holding only a `//` comment.
+ */
+interface XcconfigComment {
+  kind: "comment";
+  /** The comment text after `//`, untrimmed. */
+  text: string;
+  /** The exact source line, without its terminator. */
+  raw: string;
+  /** The line terminator, `"\n"`, `"\r\n"`, or `""` on a final line. */
+  eol: string;
+}
+/**
+ * A line that is empty or holds only whitespace.
+ */
+interface XcconfigBlank {
+  kind: "blank";
+  /** The exact source line, without its terminator. */
+  raw: string;
+  /** The line terminator, `"\n"`, `"\r\n"`, or `""` on a final line. */
+  eol: string;
+}
+/**
+ * Any parsed `.xcconfig` line.
+ */
+type XcconfigStatement = XcconfigAssignment | XcconfigBlank | XcconfigComment | XcconfigInclude;
+/**
+ * A parsed `.xcconfig` file: its lines in order.
+ */
+interface XcconfigDocument {
+  statements: XcconfigStatement[];
+}
+//#endregion
+//#region src/xcconfig/model.d.ts
+/**
+ * Resolves an `#include` path to the included file's model. Returning
+ * `undefined` skips the include, which is always legal for the
+ * `#include?` form and mirrors a missing file for the strict form.
+ *
+ * Cycles are detected while a file is being expanded, by the include
+ * path exactly as written and by model instance. A cycle reached through
+ * two different spellings of the same path escapes the path check, so
+ * resolvers that memoize per path make the instance check catch it.
+ */
+type XcconfigIncludeResolver = (path: string, optional: boolean) => Xcconfig | undefined;
+/**
+ * The build context conditional assignments are matched against. Keys
+ * mirror the condition names of the format, so `KEY[sdk=iphoneos*]`
+ * matches against {@link sdk}.
+ */
+interface XcconfigBuildContext {
+  /** The SDK identifier, for example `iphoneos` or `appletvsimulator`. */
+  sdk?: string;
+  /** The architecture, for example `arm64`. */
+  arch?: string;
+  /** The configuration name, for example `Debug`. */
+  config?: string;
+}
+/**
+ * Options for {@link Xcconfig.settings}.
+ */
+interface XcconfigSettingsOptions {
+  /**
+   * Called for every `#include` directive, in document order. Without a
+   * resolver, includes contribute nothing.
+   */
+  resolveInclude?: XcconfigIncludeResolver;
+  /**
+   * The build context conditional assignments apply under. An assignment
+   * takes part when every one of its conditions matches, with trailing
+   * `*` wildcards honored the way Xcode matches SDK names. Without a
+   * context, and for dimensions the context leaves out, conditional
+   * assignments are skipped.
+   */
+  context?: XcconfigBuildContext;
+}
+/**
+ * A build configuration file with typed, mutable access to its settings.
+ *
+ * ```ts
+ * const config = Xcconfig.parse(text);
+ * config.get("PRODUCT_BUNDLE_IDENTIFIER");
+ * config.set("MARKETING_VERSION", "1.2.0");
+ * const updated = config.build();
+ * ```
+ */
+declare class Xcconfig {
+  /** The parsed document this model wraps. */
+  readonly document: XcconfigDocument;
+  private constructor();
+  /**
+   * Parses `.xcconfig` text and wraps it in a model.
+   *
+   * @throws XcconfigParseError when the text is malformed.
+   */
+  static parse(text: string): Xcconfig;
+  /**
+   * Creates an empty configuration file.
+   */
+  static create(): Xcconfig;
+  /**
+   * Serializes the current document state to `.xcconfig` text.
+   */
+  build(): string;
+  /**
+   * The names of the settings this file assigns unconditionally, in
+   * first-assignment order. Conditional assignments such as
+   * `KEY[sdk=iphoneos*]` are reachable through {@link assignments}.
+   */
+  keys(): string[];
+  /**
+   * Every assignment of this file, conditional ones included, in
+   * document order. The items are the document's own nodes, not copies,
+   * so treat them as read-only views. Writes belong on {@link set},
+   * which keeps a statement's value and its source text in step.
+   */
+  assignments(): readonly XcconfigAssignment[];
+  /**
+   * The `#include` directives of this file, in document order. The items
+   * are the document's own nodes, not copies, so treat them as read-only
+   * views.
+   */
+  includes(): readonly XcconfigInclude[];
+  /**
+   * Reads the value of a setting from this file alone. When the key is
+   * assigned more than once the last assignment wins, matching how Xcode
+   * reads the file top to bottom. Conditional assignments are ignored.
+   */
+  get(key: string): string | undefined;
+  /**
+   * Writes a setting. The last unconditional assignment of the key is
+   * rewritten in place as a canonical `KEY = value` line, replacing any
+   * trailing comment the line carried. A key the file does not assign
+   * yet is appended at the end, following the document's line-ending
+   * convention.
+   */
+  set(key: string, value: string): void;
+  /**
+   * Removes every unconditional assignment of a setting.
+   *
+   * @returns True when at least one assignment was removed.
+   */
+  remove(key: string): boolean;
+  /**
+   * Flattens the file into a settings dictionary the way Xcode reads it:
+   * top to bottom with later assignments winning, and every `#include`
+   * contributing its settings at the point of the directive, so lines
+   * after an include override it.
+   *
+   * Conditional assignments apply when every condition matches
+   * {@link XcconfigSettingsOptions.context}; without a context they are
+   * skipped. `$(inherited)` references splice in the value accumulated
+   * earlier in the chain, and stay literal when there is none, since
+   * they then refer to layers below the file, which resolve later.
+   *
+   * Includes only take part when {@link XcconfigSettingsOptions.resolveInclude}
+   * is provided, since the library never touches the filesystem itself.
+   * A file included again later re-applies, exactly like pasting its text
+   * a second time. Only re-entry while a file is still being expanded is
+   * skipped, tracked by include path and by instance, so cyclic includes
+   * terminate even when the resolver parses a fresh instance per call.
+   */
+  settings(options?: XcconfigSettingsOptions): Record<string, string>;
+}
+//#endregion
 //#region src/model/project.d.ts
 /**
  * The `PBXProject` object at the document root. It owns the target list,
@@ -1288,7 +1541,7 @@ declare class RootProject extends XcodeObject<RootProjectProperties> {
   mainGroup(): Group | undefined;
   /**
    * The settings dictionary of the project-level default configuration.
-   * Targets inherit from these settings; see
+   * Targets inherit from these settings, as described on
    * {@link NativeTarget.getBuildSetting}.
    */
   defaultConfigurationSettings(): PbxprojObject | undefined;
@@ -1351,6 +1604,12 @@ declare class XcodeProject {
    * access, so views of the same object compare with `===`.
    */
   private readonly views;
+  /**
+   * Flattened settings of registered `.xcconfig` files, keyed by the id
+   * of the file reference configurations name in
+   * `baseConfigurationReference`.
+   */
+  private readonly xcconfigSettings;
   private constructor();
   /**
    * Parses pbxproj text and wraps it in a model.
@@ -1361,7 +1620,7 @@ declare class XcodeProject {
   static parse(text: string): XcodeProject;
   /**
    * Wraps an already parsed document in a model. The document is used in
-   * place, not copied; model mutations write into it.
+   * place rather than copied, so model mutations write into it.
    */
   static fromDocument(document: PbxprojObject): XcodeProject;
   /**
@@ -1372,7 +1631,7 @@ declare class XcodeProject {
   /**
    * The raw properties dictionary of an object.
    *
-   * @throws XcodeModelError when no object with the id exists; views use
+   * @throws XcodeModelError when no object with the id exists. Views use
    *   this accessor, so a view of a deleted object fails loudly instead of
    *   resurrecting the entry.
    */
@@ -1395,8 +1654,8 @@ declare class XcodeProject {
   objects(): IterableIterator<[string, XcodeObject]>;
   /**
    * Generates a deterministic 24-character id from a seed, avoiding every
-   * id the document currently contains. The id is not reserved; adding an
-   * object with it (see {@link add}) is what claims it.
+   * id the document currently contains. The id is not reserved, and only
+   * adding an object with it (see {@link add}) claims it.
    */
   generateId(seed: string): string;
   /**
@@ -1414,6 +1673,22 @@ declare class XcodeProject {
    * @returns The view of the created object.
    */
   add<I extends string>(isa: I, properties: PbxprojObject, seed?: string): ViewOf<I>;
+  /**
+   * Registers the contents of a `.xcconfig` file so build-setting reads
+   * can layer it below the configurations that are based on it. The
+   * library never touches the filesystem, so the caller loads the file
+   * and hands it over together with the file reference that
+   * configurations name in `baseConfigurationReference`. Included files
+   * take part through {@link XcconfigSettingsOptions.resolveInclude};
+   * the settings are flattened once, at registration.
+   */
+  registerXcconfig(reference: FileReference, config: Xcconfig, options?: XcconfigSettingsOptions): void;
+  /**
+   * The flattened settings registered for the `.xcconfig` file a
+   * configuration is based on, or `undefined` when the configuration
+   * names none or the file was not registered.
+   */
+  xcconfigSettingsOf(configuration: BuildConfiguration): Record<string, string> | undefined;
   /**
    * The view of the document's root `PBXProject` object.
    *
@@ -1449,7 +1724,8 @@ declare class XcodeProject {
    * and Resources build phases, and registers it on the project.
    *
    * @throws XcodeModelError for product types the model cannot create a
-   *   product reference for; see {@link AddNativeTargetOptions.productType}.
+   *   product reference for, listed on
+   *   {@link AddNativeTargetOptions.productType}.
    */
   addNativeTarget(options: AddNativeTargetOptions): NativeTarget;
   /**
@@ -1459,7 +1735,7 @@ declare class XcodeProject {
   /**
    * Adds a remote Swift package reference and registers it on the project.
    * When the project already references the repository, the existing
-   * reference is returned unchanged, requirement included; adjust an
+   * reference is returned unchanged, requirement included. Adjust an
    * existing requirement through the reference's properties. Link products
    * to targets with {@link NativeTarget.addSwiftPackageProduct}.
    *
@@ -1512,7 +1788,7 @@ declare class XcodeProject {
    * list containing it, or a nested dictionary carrying it as a key or
    * string value.
    *
-   * The scan is linear over the document; removal flows call it once per
+   * The scan is linear over the document. Removal flows call it once per
    * removed object, which keeps teardown proportional to what is actually
    * removed.
    */
@@ -1524,7 +1800,7 @@ declare class XcodeProject {
    * (such as `TargetAttributes`) drop its entry.
    *
    * Removing an id the document does not contain is a no-op. This is the
-   * low-level removal; {@link removeTarget} composes it into a full
+   * low-level removal, and {@link removeTarget} composes it into a full
    * teardown.
    */
   removeObject(id: string): void;
@@ -1537,7 +1813,7 @@ declare class XcodeProject {
    * dependencies on others), its membership exception sets, and
    * synchronized folders no remaining target links.
    *
-   * On-disk sources are untouched; the removal is document-only, like
+   * On-disk sources are untouched. The removal is document-only, like
    * deleting a target in Xcode and keeping its folder.
    *
    * @throws XcodeModelError when the target belongs to another project,
@@ -1545,13 +1821,33 @@ declare class XcodeProject {
    *   objects that happen to share them.
    */
   removeTarget(target: Target): void;
+  /**
+   * Renames a target and every place the document knows it by name. That
+   * covers the target's `name` and `productName`, its product file
+   * reference (`OldName.app` becomes `NewName.app`, whatever the
+   * extension), the `remoteInfo` of container item proxies pointing at
+   * the target, `TEST_TARGET_NAME` settings naming it, and the path
+   * segments of `TEST_HOST` and `BUNDLE_LOADER` settings that name the
+   * target or its product. A `PRODUCT_NAME` of the target's own
+   * configurations is rewritten only when it spells the old name
+   * literally. The usual `$(TARGET_NAME)` follows by itself.
+   *
+   * Scheme files live outside the pbxproj, so buildable references are
+   * renamed separately through `Xcscheme.renameTarget`. On-disk renames
+   * (source folders, entitlements files) and the group paths pointing at
+   * those folders stay with the caller. Sibling targets such as
+   * `OldNameTests` are renamed with their own calls.
+   *
+   * @throws XcodeModelError when the target belongs to another project.
+   */
+  renameTarget(target: Target, newName: string): void;
   /**
    * Finds a file reference by its project-relative path, resolving each
    * reference's location through the group tree from the main group
    * (nested group `path` components join with `/`).
    *
    * Members of file-system-synchronized folders are not listed in the
-   * document and therefore cannot be found; check
+   * document and therefore cannot be found. Check
    * {@link NativeTarget.syncGroupPaths} for folder-level containment
    * instead.
    */
@@ -1713,8 +2009,8 @@ declare class XcodeObject<Properties extends PbxprojObject = PbxprojObject> {
    * nested dictionaries keyed by object id (such as the root project's
    * `TargetAttributes`) drop its entry.
    *
-   * This is the low-level removal; it does not cascade to objects that only
-   * made sense alongside this one. Higher-level operations like
+   * This is the low-level removal, so it does not cascade to objects that
+   * only made sense alongside this one. Higher-level operations like
    * {@link XcodeProject.removeTarget} compose it into full teardowns.
    */
   removeFromProject(): void;
@@ -1732,7 +2028,7 @@ declare class XcodeObject<Properties extends PbxprojObject = PbxprojObject> {
  * @param text Source text of the document.
  * @returns The document's root value. For real project files this is the
  *   root dictionary with `objects`, `rootObject`, and version fields.
- * @throws PbxprojParseError when the document is malformed; the error
+ * @throws PbxprojParseError when the document is malformed. The error
  *   carries the line and column of the failure.
  */
 declare function parsePbxproj(text: string): PbxprojValue;
@@ -1904,6 +2200,22 @@ declare class Xcscheme {
    * of these, so rename flows iterate this list.
    */
   buildableReferences(): BuildableReference[];
+  /**
+   * Renames every buildable reference pointing at a target. The blueprint
+   * name is matched whole, and the buildable name is matched by its stem,
+   * so `OldApp.app` becomes `NewApp.app` while `OldAppTests.xctest`, a
+   * different target's product, stays untouched. This is the scheme-file
+   * side of `XcodeProject.renameTarget`. Returns whether anything
+   * changed, so callers can skip rewriting untouched files.
+   */
+  renameTarget(oldName: string, newName: string): boolean;
+  /**
+   * Rewrites every buildable reference's container after the
+   * `.xcodeproj` directory itself is renamed, so `container:Old.xcodeproj`
+   * becomes `container:New.xcodeproj`. The project names are matched
+   * exactly. Returns whether anything changed.
+   */
+  renameContainer(oldProjectName: string, newProjectName: string): boolean;
 }
 /**
  * Options for {@link createXcscheme}.
@@ -1946,7 +2258,7 @@ declare function parseXcscheme(text: string): XcschemeDocument;
  * Deterministic object identifiers for generated pbxproj objects.
  *
  * Xcode identifies every object with 24 hexadecimal characters. Generated
- * ids here are deterministic: the same seed always produces the same id, so
+ * ids here are deterministic. The same seed always produces the same id, so
  * programmatic edits are reproducible and diffs stay minimal across runs.
  * The format is `XX` + the first 20 characters of `md5(seed)` + `XX`, which
  * is a valid identifier that remains recognizable as generated.
@@ -1968,4 +2280,20 @@ declare function parseXcscheme(text: string): XcschemeDocument;
  */
 declare function generateObjectId(seed: string, existing: ReadonlySet<string>): string;
 //#endregion
-export { type AddNativeTargetOptions, AggregateTarget, type ApplePlatform, AppleScriptBuildPhase, BuildConfiguration, type BuildConfigurationProperties, BuildFile, BuildFileExceptionSet, type BuildFileProperties, BuildPhase, type BuildPhaseIsa, BuildPhaseMembershipExceptionSet, type BuildPhaseMembershipExceptionSetProperties, type BuildPhaseOf, type BuildPhaseProperties, BuildRule, type BuildRuleProperties, type BuildSettings, BuildStyle, type BuildStyleProperties, BuildableReference, ConfigurationList, type ConfigurationListProperties, ContainerItemProxy, type ContainerItemProxyProperties, CopyFilesBuildPhase, type CopyFilesBuildPhaseProperties, CopyFilesDestination, type CreateXcschemeOptions, ExceptionSet, type ExceptionSetProperties, FileReference, type FileReferenceProperties, FrameworksBuildPhase, Group, type GroupProperties, HeadersBuildPhase, Isa, type IsaValue, LegacyTarget, type LegacyTargetProperties, LocalSwiftPackageReference, type LocalSwiftPackageReferenceProperties, NativeTarget, type NativeTargetProperties, type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, ProductType, type ProjectIssue, type ProjectIssueKind, ReferenceProxy, type ReferenceProxyProperties, RemoteSwiftPackageReference, type RemoteSwiftPackageReferenceProperties, ResourcesBuildPhase, RezBuildPhase, RootProject, type RootProjectProperties, ShellScriptBuildPhase, type ShellScriptBuildPhaseProperties, SourcesBuildPhase, SwiftPackageProductDependency, type SwiftPackageProductDependencyProperties, SwiftPackageReference, type SwiftPackageReferenceProperties, SyncRootGroup, type SyncRootGroupProperties, Target, TargetDependency, type TargetDependencyProperties, type TargetProperties, VariantGroup, VersionGroup, type VersionGroupProperties, type ViewByIsa, type ViewOf, XcodeModelError, XcodeObject, XcodeProject, Xcscheme, XcschemeBuildError, type XcschemeComment, type XcschemeDocument, type XcschemeElement, type XcschemeNode, XcschemeParseError, buildPbxproj, buildXcscheme, createXcscheme, generateObjectId, isXcschemeElement, parseApplePlatform, parsePbxproj, parseXcscheme, xcschemeElements };
+//#region src/xcconfig/build.d.ts
+/**
+ * Serializes a document back to `.xcconfig` text.
+ */
+declare function buildXcconfig(document: XcconfigDocument): string;
+//#endregion
+//#region src/xcconfig/parse.d.ts
+/**
+ * Parses `.xcconfig` text into its document form.
+ *
+ * @throws XcconfigParseError when a line is not a blank, a comment, an
+ *   include, or a well-formed assignment. The error carries the line and
+ *   column of the failure.
+ */
+declare function parseXcconfig(source: string): XcconfigDocument;
+//#endregion
+export { type AddNativeTargetOptions, AggregateTarget, type ApplePlatform, AppleScriptBuildPhase, BuildConfiguration, type BuildConfigurationProperties, BuildFile, BuildFileExceptionSet, type BuildFileProperties, BuildPhase, type BuildPhaseIsa, BuildPhaseMembershipExceptionSet, type BuildPhaseMembershipExceptionSetProperties, type BuildPhaseOf, type BuildPhaseProperties, BuildRule, type BuildRuleProperties, type BuildSettings, BuildStyle, type BuildStyleProperties, BuildableReference, ConfigurationList, type ConfigurationListProperties, ContainerItemProxy, type ContainerItemProxyProperties, CopyFilesBuildPhase, type CopyFilesBuildPhaseProperties, CopyFilesDestination, type CreateXcschemeOptions, ExceptionSet, type ExceptionSetProperties, FileReference, type FileReferenceProperties, FrameworksBuildPhase, Group, type GroupProperties, HeadersBuildPhase, Isa, type IsaValue, LegacyTarget, type LegacyTargetProperties, LocalSwiftPackageReference, type LocalSwiftPackageReferenceProperties, NativeTarget, type NativeTargetProperties, type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, ProductType, type ProjectIssue, type ProjectIssueKind, ReferenceProxy, type ReferenceProxyProperties, RemoteSwiftPackageReference, type RemoteSwiftPackageReferenceProperties, ResourcesBuildPhase, RezBuildPhase, RootProject, type RootProjectProperties, ShellScriptBuildPhase, type ShellScriptBuildPhaseProperties, SourcesBuildPhase, SwiftPackageProductDependency, type SwiftPackageProductDependencyProperties, SwiftPackageReference, type SwiftPackageReferenceProperties, SyncRootGroup, type SyncRootGroupProperties, Target, TargetDependency, type TargetDependencyProperties, type TargetProperties, VariantGroup, VersionGroup, type VersionGroupProperties, type ViewByIsa, type ViewOf, Xcconfig, type XcconfigAssignment, type XcconfigBlank, type XcconfigComment, type XcconfigCondition, type XcconfigDocument, type XcconfigInclude, type XcconfigIncludeResolver, XcconfigParseError, type XcconfigSettingsOptions, type XcconfigStatement, XcodeModelError, XcodeObject, XcodeProject, Xcscheme, XcschemeBuildError, type XcschemeComment, type XcschemeDocument, type XcschemeElement, type XcschemeNode, XcschemeParseError, buildPbxproj, buildXcconfig, buildXcscheme, createXcscheme, generateObjectId, isXcschemeElement, parseApplePlatform, parsePbxproj, parseXcconfig, parseXcscheme, xcschemeElements };