rork-xcode 0.8.0 → 0.9.0

package/README.md

@@ -266,6 +266,47 @@ const text = scheme.build();
 
 Underneath, the document is a plain tree of elements with ordered attributes and children, reachable through `scheme.root` and `scheme.elements(name)`, so anything the typed surface does not cover stays one property away. `parseXcscheme` and `buildXcscheme` remain available for working with the tree directly. Attribute order is preserved and meaningful, which is how byte-identical round-trips fall out. Comments are kept, attribute values resolve the character references Xcode writes (`"`, `&`, `
` and friends), and the writer re-escapes them identically.
 
+## 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.
+
+`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:
+
+```ts
+import { Xcconfig } from "rork-xcode";
+
+const config = Xcconfig.parse(xcconfigText);
+
+config.get("PRODUCT_BUNDLE_IDENTIFIER"); // last unconditional assignment wins
+config.set("MARKETING_VERSION", "1.2.0"); // rewrites in place, appends when new
+const settings = config.settings(); // flattened, the way Xcode reads the file
+
+const text = config.build();
+```
+
+`#include` directives are exposed as data because the library never touches the filesystem. Flattening resolves them through a caller-supplied lookup and applies each file at its directive's position, cycle-safe, so lines after an include override it exactly like textual inclusion. Position matters: an include hoisted or reordered changes what the file means, so the model never moves one.
+
+```ts
+const settings = config.settings({
+  resolveInclude: (path, optional) => loadedConfigs.get(path),
+});
+```
+
+Conditional assignments like `OTHER_LDFLAGS[sdk=iphoneos*][arch=arm64]` are parsed structurally with their conditions preserved verbatim on round-trip, unknown condition names included. Passing a build context applies them during flattening, with every condition required to match and trailing `*` wildcards honored; without a context they stay out, which mirrors reading the file with no build in mind. `$(inherited)` references splice in the value accumulated earlier in the chain and stay literal when there is none, so lower layers can still resolve them:
+
+```ts
+const settings = config.settings({
+  context: { sdk: "iphoneos", arch: "arm64", config: "Release" },
+});
+```
+
+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:
+
+```ts
+project.registerXcconfig(reference, Xcconfig.parse(text));
+app.getBuildSetting("SDKROOT"); // now sees values the xcconfig defines
+```
+
 ## 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.
@@ -297,7 +338,7 @@ Measured on an Apple M5 Max, Node.js 24, single thread, with `@bacons/xcode` 1.0
 - 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.
 - 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 and scheme on the machine, verifies each one parses and reaches a byte-stable fixed point, exercises the object model against every project, and cross-validates a sample against plutil's own reading.
+- 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.
 
 ## Releasing

package/dist/index.d.ts

@@ -133,6 +133,25 @@ declare class XcschemeParseError extends Error {
    */
   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`.
+   */
+  constructor(message: string, source: string, offset: number);
+}
 /**
  * Thrown when a scheme element cannot be written as XML.
  *
@@ -608,6 +627,11 @@ declare class Target<Properties extends TargetProperties = TargetProperties> ext
    * generated app templates set values like `SDKROOT` only at the project
    * level.
    *
+   * 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.
+   *
    * Only string values are returned; a list- or number-valued setting reads
    * as `undefined`.
    */
@@ -1128,6 +1152,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 +1301,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,
@@ -1351,6 +1603,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.
@@ -1414,6 +1672,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.
    *
@@ -1968,4 +2242,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 };

package/dist/index.js

@@ -283,6 +283,30 @@ var XcschemeParseError = class extends Error {
 	}
 };
 /**
+* 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.
+*/
+var XcconfigParseError = class extends Error {
+	/** Where in the source text parsing failed. */
+	position;
+	/**
+	* @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, source, offset) {
+		const position = positionAt(source, offset);
+		super(`${message} (line ${position.line}, column ${position.column})`);
+		this.name = "XcconfigParseError";
+		this.position = position;
+	}
+};
+/**
 * Thrown when a scheme element cannot be written as XML.
 *
 * Raised for element and attribute names that are not valid XML names and
@@ -1587,6 +1611,16 @@ var BuildConfiguration = class extends XcodeObject {
 	get buildSettings() {
 		return asDictionary(this.properties["buildSettings"]);
 	}
+	/**
+	* 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() {
+		const view = this.project.get(this.getString("baseConfigurationReference"));
+		return FileReference.is(view) ? view : void 0;
+	}
 };
 /**
 * A `PBXBuildStyle` is the pre-Xcode-2 predecessor of
@@ -2880,16 +2914,23 @@ function configurationsOf(project, configurationListId) {
 	return configurations;
 }
 /**
-* The settings dictionary of a configuration list's default configuration:
-* the one named by `defaultConfigurationName`, falling back to the first
-* configuration. Returns `undefined` when the list has no configurations
-* or the default carries no settings dictionary.
+* The view of a configuration list's default configuration, which is the
+* one named by `defaultConfigurationName`, falling back to the first
+* configuration. Returns `undefined` when the list has no configurations.
 */
-function defaultConfigurationSettingsOf(project, configurationListId) {
+function defaultConfigurationOf(project, configurationListId) {
 	const list = asDictionary(project.propertiesOfOptional(configurationListId));
 	const configurations = configurationsOf(project, configurationListId);
 	const defaultName = asString(list?.["defaultConfigurationName"]);
-	return asDictionary((configurations.find((configuration) => configuration.getString("name") === defaultName) ?? configurations[0])?.properties["buildSettings"]);
+	return configurations.find((configuration) => configuration.getString("name") === defaultName) ?? configurations[0];
+}
+/**
+* The settings dictionary of a configuration list's default configuration
+* (see {@link defaultConfigurationOf}). Returns `undefined` when the list
+* has no configurations or the default carries no settings dictionary.
+*/
+function defaultConfigurationSettingsOf(project, configurationListId) {
+	return asDictionary(defaultConfigurationOf(project, configurationListId)?.properties["buildSettings"]);
 }
 //#endregion
 //#region src/model/target.ts
@@ -2950,13 +2991,24 @@ var Target = class extends XcodeObject {
 	* generated app templates set values like `SDKROOT` only at the project
 	* level.
 	*
+	* 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.
+	*
 	* Only string values are returned; a list- or number-valued setting reads
 	* as `undefined`.
 	*/
 	getBuildSetting(key) {
-		const targetSettings = this.defaultConfigurationSettings();
+		const targetConfiguration = defaultConfigurationOf(this.project, this.getString("buildConfigurationList"));
+		const targetSettings = asDictionary(targetConfiguration?.properties["buildSettings"]);
 		if (targetSettings != null && key in targetSettings) return asString(targetSettings[key]);
-		return asString(this.project.rootProject.defaultConfigurationSettings()?.[key]);
+		const targetXcconfig = targetConfiguration == null ? void 0 : this.project.xcconfigSettingsOf(targetConfiguration);
+		if (targetXcconfig != null && key in targetXcconfig) return targetXcconfig[key];
+		const projectConfiguration = defaultConfigurationOf(this.project, this.project.rootProject.getString("buildConfigurationList"));
+		const projectSettings = asDictionary(projectConfiguration?.properties["buildSettings"]);
+		if (projectSettings != null && key in projectSettings) return asString(projectSettings[key]);
+		return (projectConfiguration == null ? void 0 : this.project.xcconfigSettingsOf(projectConfiguration))?.[key];
 	}
 	/**
 	* Writes a build setting on every configuration of the target, so Debug
@@ -3400,6 +3452,12 @@ var XcodeProject = class XcodeProject {
 	* access, so views of the same object compare with `===`.
 	*/
 	views = /* @__PURE__ */ new Map();
+	/**
+	* Flattened settings of registered `.xcconfig` files, keyed by the id
+	* of the file reference configurations name in
+	* `baseConfigurationReference`.
+	*/
+	xcconfigSettings = /* @__PURE__ */ new Map();
 	constructor(document) {
 		const objects = asDictionary(document["objects"]);
 		if (objects == null) throw new XcodeModelError("The document has no objects dictionary");
@@ -3508,6 +3566,27 @@ var XcodeProject = class XcodeProject {
 		return view;
 	}
 	/**
+	* 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, config, options = {}) {
+		this.xcconfigSettings.set(reference.id, config.settings(options));
+	}
+	/**
+	* 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) {
+		const referenceId = configuration.getString("baseConfigurationReference");
+		return referenceId == null ? void 0 : this.xcconfigSettings.get(referenceId);
+	}
+	/**
 	* The view of the document's root `PBXProject` object.
 	*
 	* @throws XcodeModelError when `rootObject` is missing or dangling,
@@ -4557,4 +4636,328 @@ function createXcscheme(options) {
 	};
 }
 //#endregion
-export { AggregateTarget, AppleScriptBuildPhase, BuildConfiguration, BuildFile, BuildFileExceptionSet, BuildPhase, BuildPhaseMembershipExceptionSet, BuildRule, BuildStyle, BuildableReference, ConfigurationList, ContainerItemProxy, CopyFilesBuildPhase, CopyFilesDestination, ExceptionSet, FileReference, FrameworksBuildPhase, Group, HeadersBuildPhase, Isa, LegacyTarget, LocalSwiftPackageReference, NativeTarget, PbxprojBuildError, PbxprojParseError, ProductType, ReferenceProxy, RemoteSwiftPackageReference, ResourcesBuildPhase, RezBuildPhase, RootProject, ShellScriptBuildPhase, SourcesBuildPhase, SwiftPackageProductDependency, SwiftPackageReference, SyncRootGroup, Target, TargetDependency, VariantGroup, VersionGroup, XcodeModelError, XcodeObject, XcodeProject, Xcscheme, XcschemeBuildError, XcschemeParseError, buildPbxproj, buildXcscheme, createXcscheme, generateObjectId, isXcschemeElement, parseApplePlatform, parsePbxproj, parseXcscheme, xcschemeElements };
+//#region src/xcconfig/build.ts
+/**
+* Serializes a document back to `.xcconfig` text.
+*/
+function buildXcconfig(document) {
+	let text = "";
+	for (const statement of document.statements) text += statement.raw + statement.eol;
+	return text;
+}
+//#endregion
+//#region src/xcconfig/parse.ts
+/**
+* Parser for Xcode build configuration files (`.xcconfig`).
+*
+* The grammar is line based. A line is blank, a `//` comment, an
+* `#include "path"` directive, or a `KEY[conditions] = value` assignment.
+* `//` starts a comment anywhere on a line, including inside values, which
+* matches Xcode's reading of the format. Every parsed statement keeps its
+* exact source text, so an untouched document rebuilds byte for byte.
+*
+* @module
+*/
+/**
+* Matches `#include "path"` and `#include? "path"`, with an optional
+* trailing comment.
+*/
+const INCLUDE_PATTERN = /^#include(\?)?\s*"([^"]*)"\s*(?:\/\/.*)?$/u;
+/**
+* Matches the head of an assignment: leading whitespace, the setting
+* name, and the raw conditions block up to the equals sign.
+*/
+const ASSIGNMENT_HEAD_PATTERN = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*((?:\[[^\]]*\])*)\s*=/u;
+/**
+* Matches one `[name=value]` condition group inside the conditions block.
+*/
+const CONDITION_PATTERN = /\[([^=\]]+)=([^\]]*)\]/gu;
+/**
+* Strips the trailing comment, surrounding whitespace, and one trailing
+* semicolon from an assignment's right-hand side. Xcode tolerates the
+* semicolon as a leftover from property-list habits and ignores it.
+*/
+function cleanValue(rightHandSide) {
+	const commentStart = rightHandSide.indexOf("//");
+	const trimmed = (commentStart === -1 ? rightHandSide : rightHandSide.slice(0, commentStart)).trim();
+	return trimmed.endsWith(";") ? trimmed.slice(0, -1).trimEnd() : trimmed;
+}
+/**
+* Parses the conditions block of an assignment, for example
+* `[sdk=iphoneos*][arch=arm64]`.
+*
+* @throws XcconfigParseError when the block has content that is not a
+*   well-formed `[name=value]` sequence.
+*/
+function parseConditions(block, source, blockOffset) {
+	const conditions = [];
+	let consumed = 0;
+	for (const match of block.matchAll(CONDITION_PATTERN)) {
+		if (match.index !== consumed) throw new XcconfigParseError("Malformed setting condition", source, blockOffset + consumed);
+		conditions.push({
+			name: match[1].trim(),
+			value: match[2].trim()
+		});
+		consumed = match.index + match[0].length;
+	}
+	if (consumed !== block.length) throw new XcconfigParseError("Malformed setting condition", source, blockOffset + consumed);
+	return conditions;
+}
+/**
+* Parses one line into a statement.
+*
+* @param content The line without its terminator.
+* @param source The full source text, for error positions.
+* @param lineOffset Offset of the line inside `source`.
+*/
+function parseLine(content, eol, source, lineOffset) {
+	const trimmed = content.trim();
+	if (trimmed === "") return {
+		kind: "blank",
+		raw: content,
+		eol
+	};
+	if (trimmed.startsWith("//")) return {
+		kind: "comment",
+		text: trimmed.slice(2),
+		raw: content,
+		eol
+	};
+	if (trimmed.startsWith("#")) {
+		const include = INCLUDE_PATTERN.exec(trimmed);
+		if (include == null) throw new XcconfigParseError("Malformed #include directive", source, lineOffset + content.indexOf("#"));
+		return {
+			kind: "include",
+			path: include[2],
+			optional: include[1] === "?",
+			raw: content,
+			eol
+		};
+	}
+	const head = ASSIGNMENT_HEAD_PATTERN.exec(content);
+	if (head == null) throw new XcconfigParseError("Expected a setting assignment, an #include directive, or a // comment", source, lineOffset + (content.length - content.trimStart().length));
+	const conditionsBlock = head[2];
+	const conditionsOffset = lineOffset + head[0].indexOf(conditionsBlock, head[1].length);
+	const conditions = conditionsBlock === "" ? [] : parseConditions(conditionsBlock, source, conditionsOffset);
+	return {
+		kind: "assignment",
+		key: head[1],
+		conditions,
+		value: cleanValue(content.slice(head[0].length)),
+		raw: content,
+		eol
+	};
+}
+/**
+* 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.
+*/
+function parseXcconfig(source) {
+	if (source === "") return { statements: [] };
+	const statements = [];
+	let offset = 0;
+	while (offset < source.length) {
+		const lineFeed = source.indexOf("\n", offset);
+		const end = lineFeed === -1 ? source.length : lineFeed;
+		const hasCarriageReturn = end > offset && source.charCodeAt(end - 1) === 13;
+		const content = source.slice(offset, hasCarriageReturn ? end - 1 : end);
+		const eol = lineFeed === -1 ? "" : hasCarriageReturn ? "\r\n" : "\n";
+		statements.push(parseLine(content, eol, source, offset));
+		if (lineFeed === -1) break;
+		offset = lineFeed + 1;
+	}
+	return { statements };
+}
+//#endregion
+//#region src/xcconfig/model.ts
+/**
+* Object model for Xcode build configuration files (`.xcconfig`).
+*
+* {@link Xcconfig} wraps a parsed document the way `XcodeProject` wraps a
+* pbxproj: the document stays the single source of truth, reads and
+* writes go through it, and {@link Xcconfig.build} emits it back with
+* untouched lines preserved byte for byte.
+*
+* @module
+*/
+/**
+* Whether a condition value matches a context value. A bare `*` matches
+* anything, a trailing `*` matches by prefix, and anything else matches
+* exactly.
+*/
+function matchesCondition(conditionValue, contextValue) {
+	if (conditionValue === "*") return true;
+	if (conditionValue.endsWith("*")) return contextValue.startsWith(conditionValue.slice(0, -1));
+	return conditionValue === contextValue;
+}
+/**
+* Splices a prior value into `$(inherited)` and `${inherited}`
+* references. With no prior value the references stay literal, because
+* they then refer to layers below the file chain, which resolve later.
+*/
+function spliceInherited(value, prior) {
+	if (prior == null) return value;
+	return value.replaceAll("$(inherited)", prior).replaceAll("${inherited}", prior);
+}
+/**
+* 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();
+* ```
+*/
+var Xcconfig = class Xcconfig {
+	/** The parsed document this model wraps. */
+	document;
+	constructor(document) {
+		this.document = document;
+	}
+	/**
+	* Parses `.xcconfig` text and wraps it in a model.
+	*
+	* @throws XcconfigParseError when the text is malformed.
+	*/
+	static parse(text) {
+		return new Xcconfig(parseXcconfig(text));
+	}
+	/**
+	* Creates an empty configuration file.
+	*/
+	static create() {
+		return new Xcconfig({ statements: [] });
+	}
+	/**
+	* Serializes the current document state to `.xcconfig` text.
+	*/
+	build() {
+		return buildXcconfig(this.document);
+	}
+	/**
+	* 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() {
+		const keys = [];
+		for (const statement of this.document.statements) if (statement.kind === "assignment" && statement.conditions.length === 0 && !keys.includes(statement.key)) keys.push(statement.key);
+		return keys;
+	}
+	/**
+	* 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() {
+		return this.document.statements.filter((statement) => statement.kind === "assignment");
+	}
+	/**
+	* 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() {
+		return this.document.statements.filter((statement) => statement.kind === "include");
+	}
+	/**
+	* 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) {
+		let value;
+		for (const statement of this.document.statements) if (statement.kind === "assignment" && statement.key === key && statement.conditions.length === 0) value = statement.value;
+		return value;
+	}
+	/**
+	* 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, value) {
+		let target;
+		for (const statement of this.document.statements) if (statement.kind === "assignment" && statement.key === key && statement.conditions.length === 0) target = statement;
+		if (target != null) {
+			target.value = value;
+			target.raw = `${key} = ${value}`;
+			return;
+		}
+		const eol = this.document.statements.find((statement) => statement.eol !== "")?.eol ?? "\n";
+		const last = this.document.statements.at(-1);
+		if (last != null && last.eol === "") last.eol = eol;
+		this.document.statements.push({
+			kind: "assignment",
+			key,
+			conditions: [],
+			value,
+			raw: `${key} = ${value}`,
+			eol
+		});
+	}
+	/**
+	* Removes every unconditional assignment of a setting.
+	*
+	* @returns True when at least one assignment was removed.
+	*/
+	remove(key) {
+		const kept = this.document.statements.filter((statement) => statement.kind !== "assignment" || statement.key !== key || statement.conditions.length > 0);
+		const removed = kept.length !== this.document.statements.length;
+		this.document.statements = kept;
+		return removed;
+	}
+	/**
+	* 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 = {}) {
+		const merged = {};
+		const pathStack = /* @__PURE__ */ new Set();
+		const instanceStack = /* @__PURE__ */ new Set();
+		const context = options.context;
+		const applies = (statement) => statement.conditions.every((condition) => {
+			const contextValue = condition.name === "sdk" || condition.name === "arch" || condition.name === "config" ? context?.[condition.name] : void 0;
+			return contextValue != null && matchesCondition(condition.value, contextValue);
+		});
+		const visit = (config) => {
+			if (instanceStack.has(config)) return;
+			instanceStack.add(config);
+			for (const statement of config.document.statements) if (statement.kind === "include") {
+				if (pathStack.has(statement.path)) continue;
+				const included = options.resolveInclude?.(statement.path, statement.optional);
+				if (included != null) {
+					pathStack.add(statement.path);
+					visit(included);
+					pathStack.delete(statement.path);
+				}
+			} else if (statement.kind === "assignment" && applies(statement)) merged[statement.key] = spliceInherited(statement.value, merged[statement.key]);
+			instanceStack.delete(config);
+		};
+		visit(this);
+		return merged;
+	}
+};
+//#endregion
+export { AggregateTarget, AppleScriptBuildPhase, BuildConfiguration, BuildFile, BuildFileExceptionSet, BuildPhase, BuildPhaseMembershipExceptionSet, BuildRule, BuildStyle, BuildableReference, ConfigurationList, ContainerItemProxy, CopyFilesBuildPhase, CopyFilesDestination, ExceptionSet, FileReference, FrameworksBuildPhase, Group, HeadersBuildPhase, Isa, LegacyTarget, LocalSwiftPackageReference, NativeTarget, PbxprojBuildError, PbxprojParseError, ProductType, ReferenceProxy, RemoteSwiftPackageReference, ResourcesBuildPhase, RezBuildPhase, RootProject, ShellScriptBuildPhase, SourcesBuildPhase, SwiftPackageProductDependency, SwiftPackageReference, SyncRootGroup, Target, TargetDependency, VariantGroup, VersionGroup, Xcconfig, XcconfigParseError, XcodeModelError, XcodeObject, XcodeProject, Xcscheme, XcschemeBuildError, XcschemeParseError, buildPbxproj, buildXcconfig, buildXcscheme, createXcscheme, generateObjectId, isXcschemeElement, parseApplePlatform, parsePbxproj, parseXcconfig, parseXcscheme, xcschemeElements };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rork-xcode",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Zero-dependency Xcode project (pbxproj) and scheme (xcscheme) parser, builder, and object model that runs identically in every JavaScript runtime",
   "keywords": [
     "apple",