rork-xcode 0.2.0 → 0.3.0

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/rorkai/rork-xcode/actions/workflows/ci.yml/badge.svg)](https://github.com/rorkai/rork-xcode/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/rork-xcode)](https://www.npmjs.com/package/rork-xcode)
 
-The [fastest](#performance) zero-dependency Xcode project (`project.pbxproj`) parser, builder, and object model for any JavaScript runtime: browsers, Node.js, Bun, Electron, Cloudflare Workers, and React Native.
+The [fastest](#performance) zero-dependency Xcode project (`project.pbxproj`) parser, builder, and object model for any JavaScript runtime: browsers, Node.js, Bun, Electron, Cloudflare Workers, and React Native. [Scheme files](#schemes) (`.xcscheme`) are covered with the same round-trip guarantees.
 
 ```ts
 import { parsePbxproj, buildPbxproj } from "rork-xcode";
@@ -229,6 +229,39 @@ for (const [id, object] of project.objects()) {
 - **Soft reads, loud writes.** Real-world projects can be malformed, so lookups return `undefined` where a document could omit something. Operations that cannot proceed without structure (no root project object, an unknown product type, a view whose object was deleted) throw `XcodeModelError`.
 - **Identity-mapped views.** Two lookups of the same id return the same instance, so views compare with `===`.
 
+## Schemes
+
+`.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 `parseXcscheme` and `buildXcscheme` cover 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.
+
+```ts
+import { buildXcscheme, parseXcscheme, xcschemeElements } from "rork-xcode";
+
+const scheme = parseXcscheme(xcschemeText);
+
+// The tree is plain data: elements with ordered attributes and children.
+for (const reference of xcschemeElements(scheme.root, "BuildableReference")) {
+  reference.attributes["BlueprintName"] = "RenamedApp";
+  reference.attributes["BuildableName"] = "RenamedApp.app";
+  reference.attributes["ReferencedContainer"] = "container:RenamedApp.xcodeproj";
+}
+
+const text = buildXcscheme(scheme);
+```
+
+`createXcscheme` 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
+import { createXcscheme } from "rork-xcode";
+
+const scheme = createXcscheme({
+  appName: "DemoApp",
+  blueprintIdentifier: app.id,
+});
+const text = buildXcscheme(scheme);
+```
+
+Attribute order is preserved and meaningful: the writer emits attributes in insertion order, 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.
+
 ## 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.
@@ -260,7 +293,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 on the machine, verifies each one parses and reaches a byte-stable fixed point, exercises the object model against it, and cross-validates a sample against plutil's own reading.
+- 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.
 - 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

@@ -114,6 +114,42 @@ declare class PbxprojParseError extends Error {
    */
   constructor(message: string, source: string, offset: number);
 }
+/**
+ * Thrown when the source text is not a well-formed scheme document (the
+ * XML dialect of `.xcscheme` 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 XcschemeParseError 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.
+ *
+ * Raised for element and attribute names that are not valid XML names and
+ * for attribute values carrying control characters XML 1.0 cannot encode.
+ * The {@link path} pinpoints the offending element inside the tree.
+ */
+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
+   *   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
  * document lacks the structure the operation needs (no objects dictionary,
@@ -1245,6 +1281,122 @@ declare class XcodeObject<Properties extends PbxprojObject = PbxprojObject> {
  */
 declare function parsePbxproj(text: string): PbxprojValue;
 //#endregion
+//#region src/scheme/types.d.ts
+/**
+ * The node model of a scheme document.
+ *
+ * A parsed `.xcscheme` is a tree of plain objects: elements with ordered
+ * attributes and child nodes, plus the occasional comment. All state lives
+ * in this tree. There is no wrapper class to keep in sync, so callers
+ * mutate nodes directly and serialize whatever the tree currently says.
+ *
+ * @module
+ */
+/**
+ * An XML element of a scheme document.
+ *
+ * Attribute order is preserved and meaningful: the writer emits attributes
+ * in insertion order, which is how byte-identical round-trips of
+ * Xcode-written files fall out. Assigning an existing key keeps its
+ * position, and adding a new key appends it.
+ */
+interface XcschemeElement {
+  /** Tag name, for example `Scheme` or `BuildableReference`. */
+  name: string;
+  /** Attribute values by name, in document order. */
+  attributes: Record<string, string>;
+  /** Child elements and comments, in document order. */
+  children: XcschemeNode[];
+}
+/**
+ * A comment inside a scheme document. Xcode never writes comments, but
+ * hand-edited and tool-generated schemes can carry them, and dropping
+ * them would make round-trips lossy.
+ */
+interface XcschemeComment {
+  /** The comment text between `<!--` and `-->`, verbatim. */
+  comment: string;
+}
+/**
+ * Any node a scheme element can contain.
+ */
+type XcschemeNode = XcschemeElement | XcschemeComment;
+/**
+ * A parsed scheme file: its root element plus any comments sitting
+ * outside it. Xcode writes only the root, so the comment lists are almost
+ * always empty, but files that carry them round-trip without loss.
+ */
+interface XcschemeDocument {
+  /** Comments before the root element. */
+  leading: XcschemeComment[];
+  /** The `Scheme` element. */
+  root: XcschemeElement;
+  /** Comments after the root element. */
+  trailing: XcschemeComment[];
+}
+/**
+ * Whether a node is an element rather than a comment.
+ */
+declare function isXcschemeElement(node: XcschemeNode): node is XcschemeElement;
+//#endregion
+//#region src/scheme/build.d.ts
+/**
+ * Serializes a scheme document to the text of a `.xcscheme` file.
+ *
+ * @throws XcschemeBuildError for element or attribute names that are not
+ *   XML names and for attribute values carrying unencodable control
+ *   characters, with the path of the offending node.
+ */
+declare function buildXcscheme(document: XcschemeDocument): string;
+//#endregion
+//#region src/scheme/model.d.ts
+/**
+ * Collects elements of the given name anywhere in the tree, in document
+ * order, the subtree root included. Passing no name collects every
+ * element.
+ *
+ * ```ts
+ * for (const reference of xcschemeElements(scheme.root, "BuildableReference")) {
+ *   reference.attributes["BlueprintName"] = "RenamedApp";
+ * }
+ * ```
+ */
+declare function xcschemeElements(root: XcschemeElement, name?: string): XcschemeElement[];
+/**
+ * Options for {@link createXcscheme}.
+ */
+interface CreateXcschemeOptions {
+  /** The application target's name, which also names the scheme. */
+  appName: string;
+  /**
+   * The `.xcodeproj` directory name the buildable references point at.
+   * Defaults to `<appName>.xcodeproj`.
+   */
+  xcodeprojName?: string;
+  /**
+   * The application target's object id in the project document. Xcode
+   * repairs an empty identifier on first open, so omitting it still
+   * produces a working scheme.
+   */
+  blueprintIdentifier?: string;
+}
+/**
+ * Creates the scheme Xcode writes for an application target: build,
+ * launch, profile, analyze, and archive actions wired to the app product,
+ * with Xcode's default configuration choices (Debug for development
+ * actions, Release for profiling and archiving).
+ */
+declare function createXcscheme(options: CreateXcschemeOptions): XcschemeDocument;
+//#endregion
+//#region src/scheme/parse.d.ts
+/**
+ * Parses the text of a `.xcscheme` file into its node tree.
+ *
+ * @throws XcschemeParseError when the text is not a well-formed scheme
+ *   document, with the line and column of the failure.
+ */
+declare function parseXcscheme(text: string): XcschemeDocument;
+//#endregion
 //#region src/uuid.d.ts
 /**
  * Deterministic object identifiers for generated pbxproj objects.
@@ -1272,4 +1424,4 @@ declare function parsePbxproj(text: string): PbxprojValue;
  */
 declare function generateObjectId(seed: string, existing: ReadonlySet<string>): string;
 //#endregion
-export { type AddNativeTargetOptions, AggregateTarget, type ApplePlatform, type BuildConfigurationProperties, type BuildFileProperties, BuildPhase, type BuildPhaseProperties, BuildRule, type BuildRuleProperties, type BuildSettings, type ConfigurationListProperties, type ContainerItemProxyProperties, CopyFilesDestination, type ExceptionSetProperties, type FileReferenceProperties, Group, type GroupProperties, Isa, LegacyTarget, type LegacyTargetProperties, NativeTarget, type NativeTargetProperties, type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, ProductType, type ProjectIssue, type ProjectIssueKind, ReferenceProxy, type ReferenceProxyProperties, RootProject, type RootProjectProperties, type SwiftPackageProductDependencyProperties, type SwiftPackageReferenceProperties, SyncRootGroup, type SyncRootGroupProperties, Target, type TargetDependencyProperties, type TargetProperties, VersionGroup, type VersionGroupProperties, XcodeModelError, XcodeObject, XcodeProject, buildPbxproj, generateObjectId, parsePbxproj };
+export { type AddNativeTargetOptions, AggregateTarget, type ApplePlatform, type BuildConfigurationProperties, type BuildFileProperties, BuildPhase, type BuildPhaseProperties, BuildRule, type BuildRuleProperties, type BuildSettings, type ConfigurationListProperties, type ContainerItemProxyProperties, CopyFilesDestination, type CreateXcschemeOptions, type ExceptionSetProperties, type FileReferenceProperties, Group, type GroupProperties, Isa, LegacyTarget, type LegacyTargetProperties, NativeTarget, type NativeTargetProperties, type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, ProductType, type ProjectIssue, type ProjectIssueKind, ReferenceProxy, type ReferenceProxyProperties, RootProject, type RootProjectProperties, type SwiftPackageProductDependencyProperties, type SwiftPackageReferenceProperties, SyncRootGroup, type SyncRootGroupProperties, Target, type TargetDependencyProperties, type TargetProperties, VersionGroup, type VersionGroupProperties, XcodeModelError, XcodeObject, XcodeProject, XcschemeBuildError, type XcschemeComment, type XcschemeDocument, type XcschemeElement, type XcschemeNode, XcschemeParseError, buildPbxproj, buildXcscheme, createXcscheme, generateObjectId, isXcschemeElement, parsePbxproj, parseXcscheme, xcschemeElements };

package/dist/index.js

@@ -259,6 +259,51 @@ var PbxprojParseError = class extends Error {
 	}
 };
 /**
+* Thrown when the source text is not a well-formed scheme document (the
+* XML dialect of `.xcscheme` 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 XcschemeParseError = 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 = "XcschemeParseError";
+		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
+* for attribute values carrying control characters XML 1.0 cannot encode.
+* The {@link path} pinpoints the offending element inside the tree.
+*/
+var XcschemeBuildError = class extends Error {
+	/** Path to the offending element from the root, e.g. `Scheme.BuildAction[0]`. */
+	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, path) {
+		super(`${message} (at ${path})`);
+		this.name = "XcschemeBuildError";
+		this.path = path;
+	}
+};
+/**
 * Thrown by the object model when an operation cannot proceed: the
 * document lacks the structure the operation needs (no objects dictionary,
 * no root project object), a view's object was removed from the document,
@@ -1595,11 +1640,11 @@ const IS_LITERAL_CHAR = (() => {
 	for (const ch of "_$/:.-") table[ch.charCodeAt(0)] = 1;
 	return table;
 })();
-const CODE_TAB = 9;
-const CODE_LINE_FEED = 10;
-const CODE_CARRIAGE_RETURN = 13;
-const CODE_SPACE = 32;
-const CODE_QUOTE = 34;
+const CODE_TAB$1 = 9;
+const CODE_LINE_FEED$1 = 10;
+const CODE_CARRIAGE_RETURN$1 = 13;
+const CODE_SPACE$1 = 32;
+const CODE_QUOTE$1 = 34;
 const CODE_SINGLE_QUOTE = 39;
 const CODE_OPEN_PAREN = 40;
 const CODE_CLOSE_PAREN = 41;
@@ -1607,13 +1652,13 @@ const CODE_ASTERISK = 42;
 const CODE_COMMA = 44;
 const CODE_MINUS = 45;
 const CODE_DOT = 46;
-const CODE_SLASH = 47;
+const CODE_SLASH$1 = 47;
 const CODE_ZERO = 48;
 const CODE_NINE = 57;
 const CODE_SEMICOLON = 59;
-const CODE_LESS_THAN = 60;
-const CODE_EQUALS = 61;
-const CODE_GREATER_THAN = 62;
+const CODE_LESS_THAN$1 = 60;
+const CODE_EQUALS$1 = 61;
+const CODE_GREATER_THAN$1 = 62;
 const CODE_BACKSLASH = 92;
 const CODE_OPEN_BRACE = 123;
 const CODE_CLOSE_BRACE = 125;
@@ -1625,10 +1670,10 @@ const CODE_CLOSE_BRACE = 125;
 */
 const IS_WHITESPACE = (() => {
 	const table = /* @__PURE__ */ new Uint8Array(256);
-	table[CODE_SPACE] = 1;
-	table[CODE_TAB] = 1;
-	table[CODE_CARRIAGE_RETURN] = 1;
-	table[CODE_LINE_FEED] = 1;
+	table[CODE_SPACE$1] = 1;
+	table[CODE_TAB$1] = 1;
+	table[CODE_CARRIAGE_RETURN$1] = 1;
+	table[CODE_LINE_FEED$1] = 1;
 	return table;
 })();
 /**
@@ -1644,7 +1689,7 @@ function isDigit(code) {
 * through the `read*` and `parse*` methods; there is no separate tokenizer
 * stage and no token objects.
 */
-var Parser = class {
+var Parser$1 = class {
 	/** Source text of the document being parsed. */
 	input;
 	/** Cursor position as a UTF-16 code unit offset into {@link input}. */
@@ -1691,7 +1736,7 @@ var Parser = class {
 		const length = input.length;
 		let pos = this.pos;
 		while (pos < length && IS_WHITESPACE[input.charCodeAt(pos)] === 1) pos++;
-		if (pos < length && input.charCodeAt(pos) === CODE_SLASH) pos = this.skipCommentedTrivia(pos);
+		if (pos < length && input.charCodeAt(pos) === CODE_SLASH$1) pos = this.skipCommentedTrivia(pos);
 		this.pos = pos;
 	}
 	/**
@@ -1711,7 +1756,7 @@ var Parser = class {
 		const length = input.length;
 		for (;;) {
 			const next = input.charCodeAt(pos + 1);
-			if (next === CODE_SLASH) {
+			if (next === CODE_SLASH$1) {
 				const lineEnd = input.indexOf("\n", pos + 2);
 				pos = lineEnd === -1 ? length : lineEnd;
 			} else if (next === CODE_ASTERISK) {
@@ -1723,7 +1768,7 @@ var Parser = class {
 				pos = commentEnd + 2;
 			} else return pos;
 			while (pos < length && IS_WHITESPACE[input.charCodeAt(pos)] === 1) pos++;
-			if (pos >= length || input.charCodeAt(pos) !== CODE_SLASH) return pos;
+			if (pos >= length || input.charCodeAt(pos) !== CODE_SLASH$1) return pos;
 		}
 	}
 	/**
@@ -1806,7 +1851,7 @@ var Parser = class {
 		const input = this.input;
 		const length = input.length;
 		const start = ++this.pos;
-		while (this.pos < length && input.charCodeAt(this.pos) !== CODE_GREATER_THAN) this.pos++;
+		while (this.pos < length && input.charCodeAt(this.pos) !== CODE_GREATER_THAN$1) this.pos++;
 		if (this.pos >= length) this.fail("Unterminated data run", start - 1);
 		let hex = "";
 		for (let i = start; i < this.pos; i++) {
@@ -1849,10 +1894,10 @@ var Parser = class {
 				return result;
 			}
 			let key;
-			if (code === CODE_QUOTE || code === CODE_SINGLE_QUOTE) key = this.readQuotedString();
+			if (code === CODE_QUOTE$1 || code === CODE_SINGLE_QUOTE) key = this.readQuotedString();
 			else if (IS_LITERAL_CHAR[code] === 1) key = this.readLiteral();
 			else this.fail(`Expected a key but found '${input[this.pos]}'`);
-			this.expect(CODE_EQUALS, "=");
+			this.expect(CODE_EQUALS$1, "=");
 			const value = this.parseValue();
 			this.expect(CODE_SEMICOLON, ";");
 			if (key === "__proto__") Object.defineProperty(result, key, {
@@ -1905,9 +1950,9 @@ var Parser = class {
 		const code = this.input.charCodeAt(this.pos);
 		if (code === CODE_OPEN_BRACE) return this.parseObject();
 		if (code === CODE_OPEN_PAREN) return this.parseArray();
-		if (code === CODE_QUOTE || code === CODE_SINGLE_QUOTE) return this.readQuotedString();
+		if (code === CODE_QUOTE$1 || code === CODE_SINGLE_QUOTE) return this.readQuotedString();
 		if (IS_LITERAL_CHAR[code] === 1) return interpretLiteral(this.readLiteral());
-		if (code === CODE_LESS_THAN) return this.readData();
+		if (code === CODE_LESS_THAN$1) return this.readData();
 		this.fail(`Expected a value but found '${this.input[this.pos]}'`);
 	}
 };
@@ -1961,7 +2006,7 @@ function interpretLiteral(literal) {
 *   carries the line and column of the failure.
 */
 function parsePbxproj(text) {
-	return new Parser(text).parseDocument();
+	return new Parser$1(text).parseDocument();
 }
 //#endregion
 //#region src/md5.ts
@@ -3397,4 +3442,482 @@ function stripReferences(properties, id) {
 	}
 }
 //#endregion
-export { AggregateTarget, BuildPhase, BuildRule, CopyFilesDestination, Group, Isa, LegacyTarget, NativeTarget, PbxprojBuildError, PbxprojParseError, ProductType, ReferenceProxy, RootProject, SyncRootGroup, Target, VersionGroup, XcodeModelError, XcodeObject, XcodeProject, buildPbxproj, generateObjectId, parsePbxproj };
+//#region src/scheme/types.ts
+/**
+* Whether a node is an element rather than a comment.
+*/
+function isXcschemeElement(node) {
+	return "name" in node;
+}
+//#endregion
+//#region src/scheme/build.ts
+/**
+* Serializer for the `.xcscheme` XML dialect.
+*
+* The output reproduces Xcode's own layout byte for byte: the UTF-8
+* declaration, three-space indentation, one attribute per line with
+* spaces around the equals sign, the closing angle bracket glued to the
+* last attribute, and an explicit close tag on every element. Parsing an
+* Xcode-written scheme and building it back yields the identical file,
+* and any input reaches that canonical form in one build.
+*
+* @module
+*/
+const XML_DECLARATION = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
+/** One indentation step of Xcode's scheme writer. */
+const INDENT = "   ";
+/**
+* Matches the names Xcode's scheme vocabulary uses; a stray non-name
+* (an empty string, spaces, XML syntax) must fail rather than produce a
+* document no parser accepts.
+*/
+const NAME_PATTERN = /^[A-Za-z_:][A-Za-z0-9_:.-]*$/u;
+/**
+* Matches characters that cannot appear in an attribute value: XML 1.0
+* has no representation for control characters other than tab, line
+* feed, and carriage return.
+*/
+const UNENCODABLE_PATTERN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F]/u;
+/**
+* Serializes a scheme document to the text of a `.xcscheme` file.
+*
+* @throws XcschemeBuildError for element or attribute names that are not
+*   XML names and for attribute values carrying unencodable control
+*   characters, with the path of the offending node.
+*/
+function buildXcscheme(document) {
+	let output = XML_DECLARATION;
+	for (const comment of document.leading) output += `<!--${comment.comment}-->\n`;
+	output += renderElement(document.root, 0, document.root.name);
+	for (const comment of document.trailing) output += `<!--${comment.comment}-->\n`;
+	return output;
+}
+/**
+* Renders one element with Xcode's layout: attributes each on their own
+* line indented one step past the tag, `>` glued to the last attribute,
+* children indented one step, and always an explicit close tag.
+*/
+function renderElement(element, depth, path) {
+	if (!NAME_PATTERN.test(element.name)) throw new XcschemeBuildError(`Element name ${JSON.stringify(element.name)} is not a valid XML name`, path);
+	const indent = INDENT.repeat(depth);
+	const names = Object.keys(element.attributes);
+	let output;
+	if (names.length === 0) output = `${indent}<${element.name}>\n`;
+	else {
+		output = `${indent}<${element.name}\n`;
+		const attributeIndent = indent + INDENT;
+		for (let i = 0; i < names.length; i++) {
+			const name = names[i];
+			if (!NAME_PATTERN.test(name)) throw new XcschemeBuildError(`Attribute name ${JSON.stringify(name)} is not a valid XML name`, path);
+			const value = escapeAttribute(element.attributes[name], path, name);
+			const terminator = i === names.length - 1 ? ">" : "";
+			output += `${attributeIndent}${name} = "${value}"${terminator}\n`;
+		}
+	}
+	output += renderChildren(element.children, depth + 1, path);
+	output += `${indent}</${element.name}>\n`;
+	return output;
+}
+/**
+* Renders an element's children in document order, numbering repeated
+* element names in the error path so a failure points at one node.
+*/
+function renderChildren(children, depth, path) {
+	let output = "";
+	const seen = /* @__PURE__ */ new Map();
+	for (const child of children) if (isXcschemeElement(child)) {
+		const index = seen.get(child.name) ?? 0;
+		seen.set(child.name, index + 1);
+		output += renderElement(child, depth, `${path}.${child.name}[${index}]`);
+	} else output += `${INDENT.repeat(depth)}<!--${child.comment}-->\n`;
+	return output;
+}
+/**
+* Escapes an attribute value the way Xcode's writer does: the five named
+* entities for XML syntax characters, and character references for tab,
+* line feed, and carriage return so they survive attribute-value
+* normalization on the next parse.
+*/
+function escapeAttribute(value, path, attributeName) {
+	const unencodable = UNENCODABLE_PATTERN.exec(value);
+	if (unencodable != null) throw new XcschemeBuildError(`Attribute ${attributeName} contains the control character U+${unencodable[0].charCodeAt(0).toString(16).padStart(4, "0").toUpperCase()}, which XML cannot encode`, path);
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;").replaceAll("	", "&#9;").replaceAll("\n", "&#10;").replaceAll("\r", "&#13;");
+}
+//#endregion
+//#region src/scheme/model.ts
+/**
+* Helpers over the scheme node tree: element queries and the default
+* scheme factory.
+*
+* The tree itself is plain data, so most edits are direct property
+* writes. What this module adds is the recursive query that editing
+* flows start from and a factory producing the scheme Xcode's own "New
+* Scheme" action writes for an application target.
+*
+* @module
+*/
+/**
+* Collects elements of the given name anywhere in the tree, in document
+* order, the subtree root included. Passing no name collects every
+* element.
+*
+* ```ts
+* for (const reference of xcschemeElements(scheme.root, "BuildableReference")) {
+*   reference.attributes["BlueprintName"] = "RenamedApp";
+* }
+* ```
+*/
+function xcschemeElements(root, name) {
+	const found = [];
+	const visit = (element) => {
+		if (name == null || element.name === name) found.push(element);
+		for (const child of element.children) if (isXcschemeElement(child)) visit(child);
+	};
+	visit(root);
+	return found;
+}
+/**
+* Creates the scheme Xcode writes for an application target: build,
+* launch, profile, analyze, and archive actions wired to the app product,
+* with Xcode's default configuration choices (Debug for development
+* actions, Release for profiling and archiving).
+*/
+function createXcscheme(options) {
+	const xcodeprojName = options.xcodeprojName ?? `${options.appName}.xcodeproj`;
+	/**
+	* Buildable references appear once per action; each site gets its own
+	* element so a mutation through one action cannot alias into another.
+	*/
+	const buildableReference = () => ({
+		name: "BuildableReference",
+		attributes: {
+			BuildableIdentifier: "primary",
+			BlueprintIdentifier: options.blueprintIdentifier ?? "",
+			BuildableName: `${options.appName}.app`,
+			BlueprintName: options.appName,
+			ReferencedContainer: `container:${xcodeprojName}`
+		},
+		children: []
+	});
+	return {
+		leading: [],
+		root: {
+			name: "Scheme",
+			attributes: { version: "1.7" },
+			children: [
+				{
+					name: "BuildAction",
+					attributes: {
+						parallelizeBuildables: "YES",
+						buildImplicitDependencies: "YES"
+					},
+					children: [{
+						name: "BuildActionEntries",
+						attributes: {},
+						children: [{
+							name: "BuildActionEntry",
+							attributes: {
+								buildForTesting: "YES",
+								buildForRunning: "YES",
+								buildForProfiling: "YES",
+								buildForArchiving: "YES",
+								buildForAnalyzing: "YES"
+							},
+							children: [buildableReference()]
+						}]
+					}]
+				},
+				{
+					name: "LaunchAction",
+					attributes: {
+						buildConfiguration: "Debug",
+						selectedDebuggerIdentifier: "Xcode.DebuggerFoundation.Debugger.LLDB",
+						selectedLauncherIdentifier: "Xcode.DebuggerFoundation.Launcher.LLDB",
+						launchStyle: "0",
+						useCustomWorkingDirectory: "NO",
+						ignoresPersistentStateOnLaunch: "NO",
+						debugDocumentVersioning: "YES",
+						debugServiceExtension: "internal",
+						allowLocationSimulation: "YES"
+					},
+					children: [{
+						name: "BuildableProductRunnable",
+						attributes: { runnableDebuggingMode: "0" },
+						children: [buildableReference()]
+					}]
+				},
+				{
+					name: "ProfileAction",
+					attributes: {
+						buildConfiguration: "Release",
+						shouldUseLaunchSchemeArgsEnv: "YES",
+						savedToolIdentifier: "",
+						useCustomWorkingDirectory: "NO",
+						debugDocumentVersioning: "YES"
+					},
+					children: [{
+						name: "BuildableProductRunnable",
+						attributes: { runnableDebuggingMode: "0" },
+						children: [buildableReference()]
+					}]
+				},
+				{
+					name: "AnalyzeAction",
+					attributes: { buildConfiguration: "Debug" },
+					children: []
+				},
+				{
+					name: "ArchiveAction",
+					attributes: {
+						buildConfiguration: "Release",
+						revealArchiveInOrganizer: "YES"
+					},
+					children: []
+				}
+			]
+		},
+		trailing: []
+	};
+}
+//#endregion
+//#region src/scheme/parse.ts
+/**
+* Parser for the `.xcscheme` XML dialect.
+*
+* Scheme files are XML with a narrow shape: elements with attributes and
+* child elements, no text content, no namespaces, no DOCTYPE. The parser
+* accepts that shape from any writer (attribute order, quoting style, and
+* whitespace vary across tools), resolves character and entity references
+* in attribute values, and preserves comments. Anything outside the shape
+* fails loudly with a position, in line with the pbxproj parser.
+*
+* @module
+*/
+const CODE_TAB = 9;
+const CODE_LINE_FEED = 10;
+const CODE_CARRIAGE_RETURN = 13;
+const CODE_SPACE = 32;
+const CODE_BANG = 33;
+const CODE_QUOTE = 34;
+const CODE_AMPERSAND = 38;
+const CODE_APOSTROPHE = 39;
+const CODE_HYPHEN = 45;
+const CODE_SLASH = 47;
+const CODE_LESS_THAN = 60;
+const CODE_EQUALS = 61;
+const CODE_GREATER_THAN = 62;
+const CODE_QUESTION = 63;
+const CODE_HASH = 35;
+const CODE_BOM = 65279;
+/**
+* Whether a code unit is XML whitespace (space, tab, line feed, or
+* carriage return).
+*/
+function isWhitespace(code) {
+	return code === CODE_SPACE || code === CODE_TAB || code === CODE_LINE_FEED || code === CODE_CARRIAGE_RETURN;
+}
+/**
+* Whether a code unit can start an XML name. The scheme vocabulary is
+* ASCII, so the accepted alphabet is letters, underscore, and colon.
+*/
+function isNameStart(code) {
+	return code >= 65 && code <= 90 || code >= 97 && code <= 122 || code === 95 || code === 58;
+}
+/**
+* Whether a code unit can continue an XML name.
+*/
+function isNameChar(code) {
+	return isNameStart(code) || code >= 48 && code <= 57 || code === CODE_HYPHEN || code === 46;
+}
+/** The named character entities XML 1.0 predefines. */
+const NAMED_ENTITIES = {
+	amp: "&",
+	apos: "'",
+	gt: ">",
+	lt: "<",
+	quot: "\""
+};
+/**
+* Parses the text of a `.xcscheme` file into its node tree.
+*
+* @throws XcschemeParseError when the text is not a well-formed scheme
+*   document, with the line and column of the failure.
+*/
+function parseXcscheme(text) {
+	return new Parser(text).parseDocument();
+}
+var Parser = class {
+	input;
+	pos = 0;
+	constructor(input) {
+		this.input = input;
+		if (input.charCodeAt(0) === CODE_BOM) this.pos = 1;
+	}
+	parseDocument() {
+		this.skipWhitespace();
+		this.skipDeclaration();
+		const leading = [];
+		const trailing = [];
+		this.skipWhitespace();
+		while (this.peekIsCommentStart()) {
+			leading.push(this.parseComment());
+			this.skipWhitespace();
+		}
+		const root = this.parseElement();
+		this.skipWhitespace();
+		while (this.peekIsCommentStart()) {
+			trailing.push(this.parseComment());
+			this.skipWhitespace();
+		}
+		if (this.pos < this.input.length) this.fail("Expected end of document after the root element");
+		return {
+			leading,
+			root,
+			trailing
+		};
+	}
+	/**
+	* Skips the `<?xml ... ?>` declaration when present. Its attributes are
+	* not retained: the writer always emits the canonical UTF-8 declaration.
+	*/
+	skipDeclaration() {
+		if (this.input.charCodeAt(this.pos) !== CODE_LESS_THAN || this.input.charCodeAt(this.pos + 1) !== CODE_QUESTION) return;
+		const end = this.input.indexOf("?>", this.pos + 2);
+		if (end === -1) this.fail("Unterminated XML declaration");
+		this.pos = end + 2;
+	}
+	parseElement() {
+		if (this.input.charCodeAt(this.pos) !== CODE_LESS_THAN) this.fail("Expected an element");
+		this.pos++;
+		const name = this.parseName("element name");
+		const attributes = Object.create(null);
+		for (;;) {
+			const hadWhitespace = this.skipWhitespace();
+			const code = this.input.charCodeAt(this.pos);
+			if (code === CODE_GREATER_THAN) {
+				this.pos++;
+				break;
+			}
+			if (code === CODE_SLASH && this.input.charCodeAt(this.pos + 1) === CODE_GREATER_THAN) {
+				this.pos += 2;
+				return {
+					name,
+					attributes,
+					children: []
+				};
+			}
+			if (Number.isNaN(code)) this.fail(`Unterminated <${name}> tag`);
+			if (!hadWhitespace) this.fail("Expected whitespace before an attribute");
+			const attributeName = this.parseName("attribute name");
+			this.skipWhitespace();
+			if (this.input.charCodeAt(this.pos) !== CODE_EQUALS) this.fail(`Expected = after attribute ${attributeName}`);
+			this.pos++;
+			this.skipWhitespace();
+			if (attributeName in attributes) this.fail(`Duplicate attribute ${attributeName} on <${name}>`);
+			attributes[attributeName] = this.parseAttributeValue();
+		}
+		const children = [];
+		for (;;) {
+			this.skipWhitespace();
+			const code = this.input.charCodeAt(this.pos);
+			if (Number.isNaN(code)) this.fail(`Missing </${name}> close tag`);
+			if (code !== CODE_LESS_THAN) this.fail("Unexpected text content inside an element");
+			if (this.input.charCodeAt(this.pos + 1) === CODE_SLASH) {
+				this.pos += 2;
+				const closeName = this.parseName("close tag name");
+				if (closeName !== name) this.fail(`Expected </${name}> but found </${closeName}>`);
+				this.skipWhitespace();
+				if (this.input.charCodeAt(this.pos) !== CODE_GREATER_THAN) this.fail(`Malformed </${closeName}> close tag`);
+				this.pos++;
+				return {
+					name,
+					attributes,
+					children
+				};
+			}
+			if (this.peekIsCommentStart()) children.push(this.parseComment());
+			else children.push(this.parseElement());
+		}
+	}
+	peekIsCommentStart() {
+		return this.input.charCodeAt(this.pos) === CODE_LESS_THAN && this.input.charCodeAt(this.pos + 1) === CODE_BANG && this.input.charCodeAt(this.pos + 2) === CODE_HYPHEN && this.input.charCodeAt(this.pos + 3) === CODE_HYPHEN;
+	}
+	parseComment() {
+		const end = this.input.indexOf("-->", this.pos + 4);
+		if (end === -1) this.fail("Unterminated comment");
+		const comment = this.input.slice(this.pos + 4, end);
+		this.pos = end + 3;
+		return { comment };
+	}
+	parseName(what) {
+		const start = this.pos;
+		if (!isNameStart(this.input.charCodeAt(this.pos))) this.fail(`Expected ${what}`);
+		this.pos++;
+		while (isNameChar(this.input.charCodeAt(this.pos))) this.pos++;
+		return this.input.slice(start, this.pos);
+	}
+	parseAttributeValue() {
+		const quote = this.input.charCodeAt(this.pos);
+		if (quote !== CODE_QUOTE && quote !== CODE_APOSTROPHE) this.fail("Expected a quoted attribute value");
+		this.pos++;
+		let value = "";
+		let runStart = this.pos;
+		for (;;) {
+			const code = this.input.charCodeAt(this.pos);
+			if (Number.isNaN(code)) this.fail("Unterminated attribute value");
+			if (code === quote) {
+				value += this.input.slice(runStart, this.pos);
+				this.pos++;
+				return value;
+			}
+			if (code === CODE_LESS_THAN) this.fail("Attribute values cannot contain a raw <");
+			if (code === CODE_AMPERSAND) {
+				value += this.input.slice(runStart, this.pos);
+				value += this.parseReference();
+				runStart = this.pos;
+			} else this.pos++;
+		}
+	}
+	/**
+	* Resolves one `&...;` reference with the cursor on the ampersand. The
+	* accepted forms are the five XML named entities and decimal or hex
+	* character references, which covers everything observed in
+	* Xcode-written schemes (`&quot;`, `&amp;`, `&apos;`, `&lt;`, `&gt;`,
+	* and `&#10;`-style whitespace).
+	*/
+	parseReference() {
+		const start = this.pos;
+		const end = this.input.indexOf(";", start + 1);
+		if (end === -1 || end - start > 12) this.fail("Unterminated character reference");
+		const body = this.input.slice(start + 1, end);
+		this.pos = end + 1;
+		if (body.charCodeAt(0) === CODE_HASH) {
+			const isHex = body.charCodeAt(1) === 120 || body.charCodeAt(1) === 88;
+			const digits = body.slice(isHex ? 2 : 1);
+			const radix = isHex ? 16 : 10;
+			const codePoint = Number.parseInt(digits, radix);
+			if (digits.length === 0 || Number.isNaN(codePoint) || codePoint > 1114111) this.failAt(`Invalid character reference &${body};`, start);
+			return String.fromCodePoint(codePoint);
+		}
+		const named = Object.hasOwn(NAMED_ENTITIES, body) ? NAMED_ENTITIES[body] : void 0;
+		if (named == null) this.failAt(`Unknown entity &${body};`, start);
+		return named;
+	}
+	/**
+	* Skips whitespace and reports whether any was consumed, which attribute
+	* parsing uses to require separation between attributes.
+	*/
+	skipWhitespace() {
+		const start = this.pos;
+		while (isWhitespace(this.input.charCodeAt(this.pos))) this.pos++;
+		return this.pos > start;
+	}
+	fail(message) {
+		this.failAt(message, this.pos);
+	}
+	failAt(message, offset) {
+		throw new XcschemeParseError(message, this.input, offset);
+	}
+};
+//#endregion
+export { AggregateTarget, BuildPhase, BuildRule, CopyFilesDestination, Group, Isa, LegacyTarget, NativeTarget, PbxprojBuildError, PbxprojParseError, ProductType, ReferenceProxy, RootProject, SyncRootGroup, Target, VersionGroup, XcodeModelError, XcodeObject, XcodeProject, XcschemeBuildError, XcschemeParseError, buildPbxproj, buildXcscheme, createXcscheme, generateObjectId, isXcschemeElement, parsePbxproj, parseXcscheme, xcschemeElements };

package/package.json

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