rork-xcode 0.9.0 → 0.11.0

package/README.md

@@ -100,7 +100,7 @@ const text = project.build();
 
 ### Targets and build settings
 
-`getBuildSetting` resolves hierarchically the way Xcode does: the target's default configuration first, then the project-level configuration. Writes go to every configuration of the target, so Debug and Release stay consistent.
+`getBuildSetting` resolves hierarchically the way Xcode does, reading the target's default configuration first and the project-level configuration below it. Writes go to every configuration of the target, so Debug and Release stay consistent.
 
 ```ts
 const app = project.findMainAppTarget("ios"); // "macos" | "tvos" | "watchos" | "visionos"
@@ -114,6 +114,13 @@ for (const target of project.nativeTargets()) {
 }
 ```
 
+`resolveBuildSetting` reads the same layers and expands the `$(NAME)` and `${NAME}` references in the value. Referenced settings resolve through the chain, `$(inherited)` continues from the next layer down, and `$(TARGET_NAME)` falls back to the target's name, so the template's `PRODUCT_NAME = "$(TARGET_NAME)"` resolves without any setup. References the document cannot answer (build-system paths like `$(BUILT_PRODUCTS_DIR)`) stay verbatim unless a caller-supplied lookup answers them, so nothing is invented.
+
+```ts
+app?.resolveBuildSetting("PRODUCT_NAME"); // "DemoApp", from PRODUCT_NAME = "$(TARGET_NAME)"
+app?.resolveBuildSetting("WIDGET_ID"); // "com.example.demo.widget", through PRODUCT_BUNDLE_IDENTIFIER
+```
+
 `project.targets()` returns every target kind. Aggregate targets (`PBXAggregateTarget`) and legacy external-build-tool targets (`PBXLegacyTarget`) share the full target surface, from configurations and build settings to phases and dependency wiring.
 
 ```ts
@@ -206,6 +213,17 @@ if (widget) project.removeTarget(widget);
 project.referrersOf(app.id); // every object referencing an id, for custom teardowns
 ```
 
+### Renaming
+
+`renameTarget` renames a target and every place the document knows it by name. That covers the target's `name` and `productName`, its product file reference, the `remoteInfo` of container proxies pointing at it, `TEST_TARGET_NAME` values naming it, and the path segments of `TEST_HOST` and `BUNDLE_LOADER` that name the target or its product. Names match whole, so renaming `DemoApp` leaves `DemoAppTests` alone, and a `PRODUCT_NAME` of `$(TARGET_NAME)` follows by itself. On-disk renames (source folders, entitlements files) and the group paths pointing at those folders stay with the caller.
+
+```ts
+const app = project.findMainAppTarget("ios");
+if (app) project.renameTarget(app, "RenamedApp");
+```
+
+Scheme files live next to the project rather than inside it, so the scheme model carries the counterpart (see [Schemes](#schemes)).
+
 ### Escape hatch
 
 Every view exposes its raw dictionary, so anything the typed surface does not cover stays one property away, and `project.objects()` iterates every object with its typed view:
@@ -235,25 +253,21 @@ for (const [id, object] of project.objects()) {
 
 `.xcscheme` files describe how Xcode builds, runs, tests, and archives a target. They are not property lists but a small XML dialect of their own, and the scheme module covers it with the same contract as the pbxproj functions. An Xcode-written scheme rebuilds byte for byte, any other input reaches Xcode's canonical layout in one build, and malformed input fails with a typed error carrying line and column.
 
-`Xcscheme` is the model. Buildable references are the elements editing flows touch, and they come back as typed views:
+`Xcscheme` is the model. Renames are one call per move. `renameTarget` is the scheme-file side of the project model's `renameTarget` and touches only the named target's references, and `renameContainer` follows a rename of the `.xcodeproj` directory itself. Both return whether anything changed, so callers can skip rewriting untouched files:
 
 ```ts
 import { Xcscheme } from "rork-xcode";
 
 const scheme = Xcscheme.parse(xcschemeText);
 
-// Rename the app while keeping each product's own shape, so a testable
-// like DemoAppTests.xctest stays a test bundle.
-for (const reference of scheme.buildableReferences()) {
-  const { blueprintName, buildableName } = reference;
-  if (blueprintName) reference.blueprintName = blueprintName.replace("DemoApp", "RenamedApp");
-  if (buildableName) reference.buildableName = buildableName.replace("DemoApp", "RenamedApp");
-  reference.referencedContainer = "container:RenamedApp.xcodeproj";
-}
+scheme.renameTarget("DemoApp", "RenamedApp"); // DemoAppTests stays untouched
+scheme.renameContainer("DemoApp", "RenamedApp"); // container:RenamedApp.xcodeproj
 
 const text = scheme.build();
 ```
 
+For anything else, buildable references come back as typed views through `scheme.buildableReferences()`, with property access to the blueprint name, buildable name, container, and identifier.
+
 `Xcscheme.create` produces the scheme Xcode's own "New Scheme" action writes for an application target, wired to the target's object id from the project document:
 
 ```ts
@@ -268,7 +282,7 @@ Underneath, the document is a plain tree of elements with ordered attributes and
 
 ## Xcconfig files
 
-Build settings do not only live in the pbxproj. Projects push them into `.xcconfig` files referenced through `baseConfigurationReference`, and the xcconfig module reads and writes that format with the fidelity the rest of the library promises. The format is hand-authored with no canonical layout, so the contract here is losslessness: parsing and building an untouched file reproduces it byte for byte — comments, blank lines, column alignment, and line endings included. Malformed lines fail loudly with a typed error carrying line and column rather than being dropped, so a file the parser accepts is a file it fully understood.
+Build settings do not only live in the pbxproj. Projects push them into `.xcconfig` files referenced through `baseConfigurationReference`, and the xcconfig module reads and writes that format with the fidelity the rest of the library promises. The format is hand-authored with no canonical layout, so the contract here is losslessness. Parsing and building an untouched file reproduces it byte for byte, including comments, blank lines, column alignment, and line endings. Malformed lines fail loudly with a typed error carrying line and column rather than being dropped, so a file the parser accepts is a file it fully understood.
 
 `Xcconfig` is the model. Reads follow the file top to bottom the way Xcode does, and writes edit single lines while leaving every other byte alone:
 
@@ -300,13 +314,31 @@ const settings = config.settings({
 });
 ```
 
-Registering a file on the project makes `getBuildSetting` resolve through it in Xcode's order — target settings, the target's xcconfig, project settings, the project's xcconfig:
+Registering a file on the project makes `getBuildSetting` resolve through it in Xcode's order of target settings, then the target's xcconfig, then project settings, then the project's xcconfig:
 
 ```ts
 project.registerXcconfig(reference, Xcconfig.parse(text));
 app.getBuildSetting("SDKROOT"); // now sees values the xcconfig defines
 ```
 
+## Build-setting references
+
+Values reference other build settings as `$(NAME)` and `${NAME}`, in the pbxproj, in xcconfig files, and in Info.plist templates. The syntax is Xcode's own, down to the `:` operators, and Xcode's app templates write values in exactly this shape, for example `PRODUCT_BUNDLE_IDENTIFIER = com.yourcompany.$(PRODUCT_NAME:rfc1034identifier)`. `expandBuildSettingReferences` evaluates the syntax through a caller-supplied lookup, so the same code serves all three formats. Substituted text expands recursively, names may themselves contain references (`$(SETTING_$(VARIANT))`), cycles stay finite, and a reference the lookup cannot answer stays verbatim, so partial resolution loses no information.
+
+```ts
+import { expandBuildSettingReferences } from "rork-xcode";
+
+// A value as found in a project file. The references and their operators
+// are part of the document, so the expander takes them from the text
+// rather than from options.
+const found = "com.example.$(PRODUCT_NAME:rfc1034identifier)";
+
+expandBuildSettingReferences(found, (name) => (name === "PRODUCT_NAME" ? "My App" : undefined));
+// "com.example.My-App"
+```
+
+The `:` operators are honored for `lower`, `upper`, `rfc1034identifier` (the mapping into RFC 1034 host-name characters that bundle identifiers need), `c99extidentifier`, and `default=`. A reference carrying any other operator stays verbatim rather than expanding to a wrongly transformed value. The model composes the expander with settings resolution as `target.resolveBuildSetting(key)`, described under [Targets and build settings](#targets-and-build-settings).
+
 ## Performance
 
 `rork-xcode` is measured against the pbxproj parsers on npm, [`@bacons/xcode`](https://www.npmjs.com/package/@bacons/xcode) (its `/json` parse/build entry point) and [`xcode`](https://www.npmjs.com/package/xcode) (the long-standing package used by native build tooling), on three documents: two real Xcode-written projects from the test suite and a deterministically generated five-target app with 800 source files. It is the fastest at both operations on every document, with zero dependencies.
@@ -336,7 +368,7 @@ Measured on an Apple M5 Max, Node.js 24, single thread, with `@bacons/xcode` 1.0
 ## Verification
 
 - The committed fixture corpus spans project generations from Xcode 3 to Xcode 16, captured from real projects with identifiers neutralized: synchronized folders with both exception-set kinds, classic groups, variant groups, aggregate and legacy targets, reference proxies, build rules, Swift packages, and a ~100 KiB multiplatform framework project.
-- Documents already in current Xcode's layout must round-trip byte for byte; documents from other tool generations must normalize to a byte-stable fixed point with unchanged values.
+- Documents already in current Xcode's layout must round-trip byte for byte, and documents from other tool generations must normalize to a byte-stable fixed point with unchanged values.
 - On macOS, the suite cross-validates every fixture and its rebuilt form with `plutil`, Apple's own property list parser and the empirical ground truth for what Apple tooling accepts.
 - A corpus sweep (`pnpm corpus`) walks every Xcode project, scheme, and xcconfig on the machine, verifies each one parses and reaches a byte-stable fixed point (byte-exact losslessness for xcconfig, which has no canonical layout), exercises the object model against every project, and cross-validates a sample against plutil's own reading.
 - CI runs the full gate on Linux and macOS, and executes the built artifact on the oldest supported Node to enforce the `engines` floor.

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,7 @@ 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`.
@@ -145,7 +146,7 @@ declare class XcconfigParseError 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`.
@@ -163,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.
@@ -199,26 +200,93 @@ 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, `$`.
    */
   constructor(message: string, path: string);
 }
 //#endregion
+//#region src/expansion.d.ts
+/**
+ * Expansion of `$(NAME)` and `${NAME}` build-setting references.
+ *
+ * Values in the pbxproj, in xcconfig files, and in Info.plist templates
+ * reference other build settings, and every consumer that needs the
+ * resolved string ends up re-implementing the substitution informally.
+ * The expander here is a pure function over a caller-supplied lookup, so
+ * the same code serves all three formats. The model composes it with
+ * settings resolution in `Target.resolveBuildSetting`.
+ *
+ * @module
+ */
+/**
+ * The value a reference expands to, or `undefined` to leave the
+ * reference in place. Returning the empty string expands to nothing,
+ * which is how Xcode itself treats settings that exist but are empty.
+ */
+type BuildSettingLookup = (name: string) => string | undefined;
+interface ExpandBuildSettingOptions {
+  /**
+   * Whether lookup answers are expanded again, which is the default and
+   * suits lookups reading raw stored values. A lookup that resolves
+   * references itself, like the model's layered resolution, turns this
+   * off so text it deliberately left verbatim is not reinterpreted in
+   * the outer value's context.
+   */
+  expandLookupValues?: boolean;
+}
+/**
+ * Expands every `$(NAME)` and `${NAME}` reference in a value through the
+ * lookup. Substituted text is expanded again, so references are followed
+ * through chains of values, and reference names may themselves contain
+ * references (`$(SETTING_$(VARIANT))`), which expand innermost first.
+ *
+ * A lookup answer of `undefined` leaves the reference in the output
+ * verbatim, so partial resolution loses no information. A reference
+ * whose expansion would recurse into itself also stays verbatim, which
+ * keeps cyclic definitions finite. Xcode's `:` operators are honored for
+ * the forms below, and a reference carrying any other operator stays
+ * verbatim rather than expanding to a wrongly transformed value.
+ *
+ * The supported operators are `lower` and `upper` for case mapping,
+ * `rfc1034identifier` and `c99extidentifier` for the identifier
+ * mappings bundle identifiers and product module names use, and
+ * `default=value` for substituting a fallback when the setting resolves
+ * empty or is not known to the lookup.
+ */
+declare function expandBuildSettingReferences(value: string, lookup: BuildSettingLookup, options?: ExpandBuildSettingOptions): string;
+/**
+ * The transforming operators the expander supports, keyed by the name
+ * they are written with. `default=` is not listed because it carries an
+ * argument and substitutes rather than transforms, so the reference
+ * expansion handles it structurally.
+ */
+declare const OPERATOR_TRANSFORMS: {
+  c99extidentifier: (value: string) => string;
+  lower: (value: string) => string;
+  rfc1034identifier: (value: string) => string;
+  upper: (value: string) => string;
+};
+/**
+ * A transforming operator name honored in `$(NAME:operator)` references,
+ * alongside the structural `default=`.
+ */
+type BuildSettingOperator = keyof typeof OPERATOR_TRANSFORMS;
+//#endregion
 //#region src/model/isa.d.ts
 /**
  * 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: {
@@ -592,6 +660,16 @@ interface BuildStyleProperties extends PbxprojObject {
 }
 //#endregion
 //#region src/model/target.d.ts
+interface ResolveBuildSettingOptions {
+  /**
+   * Answers references the document itself cannot, for example
+   * `$(BUILT_PRODUCTS_DIR)` when the caller knows the build layout. The
+   * lookup is consulted after the setting layers and before the built-in
+   * `$(TARGET_NAME)` fallback, and a reference it leaves unanswered
+   * stays verbatim in the result.
+   */
+  lookup?: BuildSettingLookup;
+}
 /**
  * The behavior every target kind shares. A target of any kind carries
  * build configurations and settings, build phases, and dependencies, and
@@ -629,13 +707,29 @@ declare class Target<Properties extends TargetProperties = TargetProperties> ext
    *
    * Configurations based on `.xcconfig` files take part once the files
    * are registered through {@link XcodeProject.registerXcconfig}, in
-   * Xcode's order: target settings, the target's xcconfig, project
-   * settings, the project's xcconfig.
+   * Xcode's order of target settings, then the target's xcconfig, then
+   * project settings, then the project's xcconfig.
    *
-   * Only string values are returned; a list- or number-valued setting reads
-   * as `undefined`.
+   * Only string values are returned, so a list- or number-valued setting
+   * reads as `undefined`.
    */
   getBuildSetting(key: string): string | undefined;
+  /**
+   * Reads a build setting like {@link getBuildSetting} and expands the
+   * `$(NAME)` and `${NAME}` references in it. Referenced settings resolve
+   * through the same layering, `$(inherited)` and a setting referencing
+   * itself continue from the next layer down the way Xcode composes
+   * values, and `$(TARGET_NAME)` falls back to the target's name, so the
+   * common `PRODUCT_NAME = "$(TARGET_NAME)"` resolves without any caller
+   * setup.
+   *
+   * References the model cannot resolve (build-system paths like
+   * `$(BUILT_PRODUCTS_DIR)`, environment values) stay in the result
+   * verbatim unless the caller's lookup answers them, so no information
+   * is invented. See {@link expandBuildSettingReferences} for the
+   * operator forms honored during expansion.
+   */
+  resolveBuildSetting(key: string, options?: ResolveBuildSettingOptions): string | undefined;
   /**
    * Writes a build setting on every configuration of the target, so Debug
    * and Release stay consistent.
@@ -879,7 +973,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
@@ -905,8 +999,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;
   /**
@@ -934,7 +1028,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"] }`.
@@ -1029,7 +1123,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;
   /**
@@ -1055,12 +1149,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.
@@ -1540,7 +1634,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;
@@ -1619,7 +1713,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;
   /**
@@ -1630,7 +1724,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.
    */
@@ -1653,8 +1747,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;
   /**
@@ -1723,7 +1817,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;
   /**
@@ -1733,7 +1828,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}.
    *
@@ -1786,7 +1881,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.
    */
@@ -1798,7 +1893,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;
@@ -1811,7 +1906,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,
@@ -1819,13 +1914,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.
    */
@@ -1987,8 +2102,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;
@@ -2006,7 +2121,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;
@@ -2178,6 +2293,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}.
@@ -2220,7 +2351,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.
@@ -2258,4 +2389,4 @@ declare function buildXcconfig(document: XcconfigDocument): string;
  */
 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 };
+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 BuildSettingLookup, type BuildSettingOperator, type BuildSettings, BuildStyle, type BuildStyleProperties, BuildableReference, ConfigurationList, type ConfigurationListProperties, ContainerItemProxy, type ContainerItemProxyProperties, CopyFilesBuildPhase, type CopyFilesBuildPhaseProperties, CopyFilesDestination, type CreateXcschemeOptions, ExceptionSet, type ExceptionSetProperties, type ExpandBuildSettingOptions, 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, type ResolveBuildSettingOptions, 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, expandBuildSettingReferences, generateObjectId, isXcschemeElement, parseApplePlatform, parsePbxproj, parseXcconfig, parseXcscheme, xcschemeElements };