@swiftbrowser/xcodeproj 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @swiftbrowser/xcodeproj
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reads Xcode projects without Xcode: a pure-TypeScript parser for `project.pbxproj`
+(Node built-ins only) that answers the questions a CLI has about an iOS app:
+which targets exist, which Swift files and asset catalogs they compile, and what
+their build settings are.
+
+```ts
+import { findXcodeProjects, readXcodeProject } from '@swiftbrowser/xcodeproj';
+
+const [xcodeproj] = findXcodeProjects(process.cwd()); // ./*.xcodeproj, else one level down
+const project = readXcodeProject(xcodeproj);
+const [app] = project.appTargets(); // targets whose product is an application
+
+app.name; // 'GuessTheFlag'
+app.productName; // PRODUCT_NAME with $(TARGET_NAME) resolved
+app.bundleIdentifier; // PRODUCT_BUNDLE_IDENTIFIER
+app.displayName; // INFOPLIST_KEY_CFBundleDisplayName, else CFBundleDisplayName from INFOPLIST_FILE
+app.appIconName; // ASSETCATALOG_COMPILER_APPICON_NAME
+app.swiftVersion; // SWIFT_VERSION
+app.deploymentTarget; // IPHONEOS_DEPLOYMENT_TARGET
+app.sources; // absolute paths of the .swift files, in navigator order
+app.resources; // absolute paths of the Resources build phase entries
+app.assetCatalogs; // the *.xcassets among them (and in synchronized folders)
+app.dependencies; // names of target dependencies
+app.packageProducts; // Swift package products the target links
+app.settings('Release'); // merged build settings for a configuration
+```
+
+## API
+
+- `readXcodeProject(xcodeprojPath)` parses `<xcodeprojPath>/project.pbxproj` and
+  returns an `XcodeProject`: `path`, `root` (the directory containing the
+  bundle, what `$(SRCROOT)` means), `objectVersion`, `targets` (every
+  `PBXNativeTarget`) and `appTargets()`.
+- `parsePbxproj(text)` returns the raw object graph: `{ objectVersion,
+  rootObject, objects }`, where each object has an `isa` plus arbitrary fields
+  (strings, arrays, nested dictionaries). `parseOldStylePlist(text)` parses any
+  old-style property list fragment.
+- `xcodeProjectFromDocument(doc, xcodeprojPath)` interprets an already parsed
+  document as the project at that path.
+- `findXcodeProjects(dir)` lists the `*.xcodeproj` bundles directly in `dir`,
+  else one level down (sorted), skipping `Pods/`, `Carthage/`, `DerivedData/`,
+  `.build/`, `node_modules/` and dot-directories.
+- `parseXmlPlist(text)` is the minimal XML plist reader used for `Info.plist`.
+
+## How paths are resolved
+
+A file's absolute path is the project root plus the chain of group `path`s
+leading to it, following each object's `sourceTree`: `<group>` is relative to
+the parent group, `SOURCE_ROOT` to the root, `<absolute>` is absolute; others
+(`BUILT_PRODUCTS_DIR`, `SDKROOT`, ...) fall back to the root. Groups without a
+`path` contribute nothing. Build phase files are listed in the order of the
+group tree (what the Xcode navigator shows), not the arbitrary order of the
+build phase. Paths are resolved exactly as written; a project whose group `path`
+differs from the folder on disk only in letter case works on macOS but not on a
+case-sensitive filesystem.
+
+Xcode 16 "synchronized folders" (`PBXFileSystemSynchronizedRootGroup`
+referenced from a target's `fileSystemSynchronizedGroups`) are read from disk:
+every `*.swift` under the folder (recursive, sorted) is a source of the target
+and every `*.xcassets` an asset catalog, minus the paths listed in the target's
+`PBXFileSystemSynchronizedBuildFileExceptionSet.membershipExceptions`. A folder
+missing on disk contributes nothing.
+
+## Build settings
+
+`target.settings(configuration?)` merges the project-level `buildSettings` of
+the named `XCBuildConfiguration` with the target-level ones on top. The default
+configuration is `Debug` when the target has one, else the configuration list's
+`defaultConfigurationName`. Array-valued settings are space-joined.
+`$(TARGET_NAME)`, `$(PRODUCT_NAME)`, `$(SRCROOT)` and `$(PROJECT_DIR)` (also in
+`${...}` form) are expanded; every other `$(...)` reference, including
+`$(inherited)` and modifiers such as `$(X:rfc1034identifier)`, is left as is.
+
+## Not handled
+
+- `.xcconfig` files referenced by `baseConfigurationReference` are not read, so
+  settings defined only there are absent.
+- Binary `Info.plist` files are skipped (only XML plists are read).
+- `PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet` (Xcode 16
+  per-build-phase exceptions) and `PBXBuildRule`s are ignored.
+- Workspaces (`.xcworkspace`), referenced projects (`PBXReferenceProxy`) and
+  `PBXAggregateTarget`/`PBXLegacyTarget` are not modelled; only
+  `PBXNativeTarget`s appear in `targets`.

package/dist/find.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Locating `.xcodeproj` bundles on disk, for a CLI run from a project folder.
+ */
+/**
+ * The `.xcodeproj` bundles directly in `dir`, as absolute paths (sorted). When
+ * there are none, looks one level down, skipping `Pods/`, `Carthage/`,
+ * `DerivedData/`, `.build/`, `node_modules/` and dot-directories.
+ */
+export declare function findXcodeProjects(dir: string): string[];

package/dist/find.js

@@ -0,0 +1,43 @@
+/**
+ * Locating `.xcodeproj` bundles on disk, for a CLI run from a project folder.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** Directories whose `.xcodeproj`s are generated or third party, never the user's app. */
+const IGNORED_DIRECTORIES = new Set(['Pods', 'Carthage', 'DerivedData', '.build', 'node_modules']);
+/**
+ * The `.xcodeproj` bundles directly in `dir`, as absolute paths (sorted). When
+ * there are none, looks one level down, skipping `Pods/`, `Carthage/`,
+ * `DerivedData/`, `.build/`, `node_modules/` and dot-directories.
+ */
+export function findXcodeProjects(dir) {
+    const absolute = path.resolve(dir);
+    const direct = xcodeProjectsIn(absolute);
+    if (direct.length > 0)
+        return direct;
+    const nested = [];
+    for (const entry of readDirectories(absolute)) {
+        if (IGNORED_DIRECTORIES.has(entry) || entry.startsWith('.'))
+            continue;
+        nested.push(...xcodeProjectsIn(path.join(absolute, entry)));
+    }
+    return nested.sort();
+}
+function xcodeProjectsIn(dir) {
+    return readDirectories(dir)
+        .filter((name) => name.endsWith('.xcodeproj'))
+        .sort()
+        .map((name) => path.join(dir, name));
+}
+/** Names of the subdirectories of `dir` (empty when it cannot be read). */
+function readDirectories(dir) {
+    try {
+        return fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @swiftbrowser/xcodeproj: reads Xcode projects without Xcode.
+ *
+ * - `readXcodeProject(path)` interprets `<path>/project.pbxproj` as targets
+ *   with resolved sources, asset catalogs and build settings.
+ * - `parsePbxproj(text)` gives the raw object graph.
+ * - `findXcodeProjects(dir)` locates `.xcodeproj` bundles.
+ */
+export { parsePbxproj, parseOldStylePlist, tokenizePbxproj, PbxprojSyntaxError, type PbxValue, type PbxDict, type PbxObject, type PbxprojDocument, } from './pbxproj.js';
+export { readXcodeProject, xcodeProjectFromDocument, expandVariables, APPLICATION_PRODUCT_TYPE, type XcodeProject, type XcodeTarget, } from './project.js';
+export { findXcodeProjects } from './find.js';
+export { parseXmlPlist, type PlistValue, type PlistDict } from './plist.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @swiftbrowser/xcodeproj: reads Xcode projects without Xcode.
+ *
+ * - `readXcodeProject(path)` interprets `<path>/project.pbxproj` as targets
+ *   with resolved sources, asset catalogs and build settings.
+ * - `parsePbxproj(text)` gives the raw object graph.
+ * - `findXcodeProjects(dir)` locates `.xcodeproj` bundles.
+ */
+export { parsePbxproj, parseOldStylePlist, tokenizePbxproj, PbxprojSyntaxError, } from './pbxproj.js';
+export { readXcodeProject, xcodeProjectFromDocument, expandVariables, APPLICATION_PRODUCT_TYPE, } from './project.js';
+export { findXcodeProjects } from './find.js';
+export { parseXmlPlist } from './plist.js';

package/dist/pbxproj.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Parser for `project.pbxproj`, the file inside every `.xcodeproj` bundle.
+ *
+ * The format is the old-style ASCII (NeXTSTEP) property list:
+ *
+ *     // !$*UTF8*$!
+ *     {
+ *       archiveVersion = 1;
+ *       objectVersion = 56;
+ *       objects = {
+ *         518D77712AD7303000E0BF20 (comment: ContentView.swift) = {isa = PBXFileReference; path = ContentView.swift; sourceTree = "<group>"; };
+ *         ...
+ *       };
+ *       rootObject = 518D77662AD7303000E0BF20 (comment: Project object);
+ *     }
+ *
+ * Dictionaries are `{ key = value; }`, arrays are `( a, b, )`, and every scalar is
+ * a string: either an unquoted word (letters, digits, `_ . / $ - + :` ...) or a
+ * double-quoted string with backslash escapes. Block comments (slash-star) and
+ * line comments (double slash) may appear anywhere; Xcode puts a block comment
+ * with the object's name after every object id, as sketched above. The parser
+ * is tolerant of trailing commas and of a missing `;` before `}`.
+ *
+ * This module only builds the raw object graph; `project.ts` interprets it.
+ */
+/** A pbxproj value: a string, an array of values or a dictionary of values. */
+export type PbxValue = string | PbxValue[] | PbxDict;
+export interface PbxDict {
+    [key: string]: PbxValue;
+}
+/** One entry of `objects`: every object has an `isa` class name plus arbitrary fields. */
+export interface PbxObject extends PbxDict {
+    isa: string;
+}
+/** The parsed file. `objects` is keyed by object id (usually 24 hex digits). */
+export interface PbxprojDocument {
+    archiveVersion: number;
+    objectVersion: number;
+    rootObject: string;
+    objects: Record<string, PbxObject>;
+}
+/** Thrown for malformed input; `offset` is the character index where parsing failed. */
+export declare class PbxprojSyntaxError extends Error {
+    readonly offset: number;
+    readonly line: number;
+    readonly column: number;
+    constructor(message: string, offset: number, line: number, column: number);
+}
+type TokenKind = '{' | '}' | '(' | ')' | '=' | ';' | ',' | 'string' | 'eof';
+interface Token {
+    kind: TokenKind;
+    /** The string value (unescaped) for `string` tokens; the punctuation otherwise. */
+    value: string;
+    /** Character offset of the token's first character, for error messages. */
+    offset: number;
+}
+/** Breaks the text into tokens, dropping comments. */
+export declare function tokenizePbxproj(text: string): Token[];
+/**
+ * Parses any old-style property list text into its value tree. `parsePbxproj`
+ * is the usual entry point; this one is handy for fragments and tests.
+ */
+export declare function parseOldStylePlist(text: string): PbxValue;
+/** Parses the text of a `project.pbxproj` file into its raw object graph. */
+export declare function parsePbxproj(text: string): PbxprojDocument;
+export declare function isDict(value: PbxValue | undefined): value is PbxDict;
+export {};

package/dist/pbxproj.js

@@ -0,0 +1,287 @@
+/**
+ * Parser for `project.pbxproj`, the file inside every `.xcodeproj` bundle.
+ *
+ * The format is the old-style ASCII (NeXTSTEP) property list:
+ *
+ *     // !$*UTF8*$!
+ *     {
+ *       archiveVersion = 1;
+ *       objectVersion = 56;
+ *       objects = {
+ *         518D77712AD7303000E0BF20 (comment: ContentView.swift) = {isa = PBXFileReference; path = ContentView.swift; sourceTree = "<group>"; };
+ *         ...
+ *       };
+ *       rootObject = 518D77662AD7303000E0BF20 (comment: Project object);
+ *     }
+ *
+ * Dictionaries are `{ key = value; }`, arrays are `( a, b, )`, and every scalar is
+ * a string: either an unquoted word (letters, digits, `_ . / $ - + :` ...) or a
+ * double-quoted string with backslash escapes. Block comments (slash-star) and
+ * line comments (double slash) may appear anywhere; Xcode puts a block comment
+ * with the object's name after every object id, as sketched above. The parser
+ * is tolerant of trailing commas and of a missing `;` before `}`.
+ *
+ * This module only builds the raw object graph; `project.ts` interprets it.
+ */
+/** Thrown for malformed input; `offset` is the character index where parsing failed. */
+export class PbxprojSyntaxError extends Error {
+    offset;
+    line;
+    column;
+    constructor(message, offset, line, column) {
+        super(`${message} (line ${line}, column ${column})`);
+        this.offset = offset;
+        this.line = line;
+        this.column = column;
+        this.name = 'PbxprojSyntaxError';
+    }
+}
+const PUNCTUATION = new Set(['{', '}', '(', ')', '=', ';', ',']);
+/** Characters that end an unquoted word (besides whitespace and comment starts). */
+const WORD_TERMINATORS = new Set([...PUNCTUATION, '"']);
+function isWhitespace(ch) {
+    return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r' || ch === '\f' || ch === '\v';
+}
+/** Escape sequences recognised inside quoted strings (besides `\\uXXXX`, octal and the quote/backslash themselves). */
+const SIMPLE_ESCAPES = {
+    n: '\n',
+    t: '\t',
+    r: '\r',
+    a: '\x07',
+    b: '\b',
+    f: '\f',
+    v: '\v',
+    '"': '"',
+    "'": "'",
+    '\\': '\\',
+};
+/** Breaks the text into tokens, dropping comments. */
+export function tokenizePbxproj(text) {
+    const tokens = [];
+    const length = text.length;
+    let i = 0;
+    // A function declaration (not an arrow) so TypeScript treats calls as assertions.
+    function fail(message, offset) {
+        throw syntaxError(text, message, offset);
+    }
+    while (i < length) {
+        const ch = text[i];
+        if (isWhitespace(ch)) {
+            i++;
+            continue;
+        }
+        // Comments: `/* ... */` and `// ...` to end of line.
+        if (ch === '/' && text[i + 1] === '*') {
+            const end = text.indexOf('*/', i + 2);
+            if (end < 0)
+                fail('Unterminated block comment', i);
+            i = end + 2;
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '/') {
+            const end = text.indexOf('\n', i + 2);
+            i = end < 0 ? length : end + 1;
+            continue;
+        }
+        if (PUNCTUATION.has(ch)) {
+            tokens.push({ kind: ch, value: ch, offset: i });
+            i++;
+            continue;
+        }
+        if (ch === '"') {
+            const start = i;
+            i++;
+            let value = '';
+            for (;;) {
+                if (i >= length)
+                    fail('Unterminated string', start);
+                const c = text[i];
+                if (c === '"') {
+                    i++;
+                    break;
+                }
+                if (c !== '\\') {
+                    value += c;
+                    i++;
+                    continue;
+                }
+                // Backslash escape.
+                const e = text[i + 1];
+                if (e === undefined)
+                    fail('Unterminated string', start);
+                if (e === 'U' || e === 'u') {
+                    // `\Uxxxx`: up to four hex digits.
+                    const hex = /^[0-9a-fA-F]{1,4}/.exec(text.slice(i + 2, i + 6));
+                    if (!hex)
+                        fail('Invalid \\U escape', i);
+                    value += String.fromCharCode(parseInt(hex[0], 16));
+                    i += 2 + hex[0].length;
+                }
+                else if (e >= '0' && e <= '7') {
+                    // `\ooo`: up to three octal digits.
+                    const oct = /^[0-7]{1,3}/.exec(text.slice(i + 1, i + 4));
+                    value += String.fromCharCode(parseInt(oct[0], 8));
+                    i += 1 + oct[0].length;
+                }
+                else {
+                    // Unknown escapes keep the character (`\x` -> `x`), like Foundation does.
+                    value += SIMPLE_ESCAPES[e] ?? e;
+                    i += 2;
+                }
+            }
+            tokens.push({ kind: 'string', value, offset: start });
+            continue;
+        }
+        // Unquoted word: runs until whitespace, punctuation, a quote or a comment start.
+        const start = i;
+        while (i < length) {
+            const c = text[i];
+            if (isWhitespace(c) || WORD_TERMINATORS.has(c))
+                break;
+            if (c === '/' && (text[i + 1] === '*' || text[i + 1] === '/'))
+                break;
+            i++;
+        }
+        if (i === start)
+            fail(`Unexpected character ${JSON.stringify(ch)}`, i);
+        tokens.push({ kind: 'string', value: text.slice(start, i), offset: start });
+    }
+    tokens.push({ kind: 'eof', value: '', offset: length });
+    return tokens;
+}
+function syntaxError(text, message, offset) {
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < offset && i < text.length; i++) {
+        if (text[i] === '\n') {
+            line++;
+            lineStart = i + 1;
+        }
+    }
+    return new PbxprojSyntaxError(message, offset, line, offset - lineStart + 1);
+}
+// ----- Parser --------------------------------------------------------------
+class Parser {
+    text;
+    tokens;
+    pos = 0;
+    constructor(text, tokens) {
+        this.text = text;
+        this.tokens = tokens;
+    }
+    peek() {
+        return this.tokens[this.pos];
+    }
+    next() {
+        const token = this.tokens[this.pos];
+        if (token.kind !== 'eof')
+            this.pos++;
+        return token;
+    }
+    fail(message, token = this.peek()) {
+        const found = token.kind === 'eof' ? 'end of input' : JSON.stringify(token.value);
+        throw syntaxError(this.text, `${message}, found ${found}`, token.offset);
+    }
+    expect(kind) {
+        const token = this.peek();
+        if (token.kind !== kind)
+            this.fail(`Expected ${kind}`);
+        return this.next();
+    }
+    /** Parses the whole document: one top-level value followed by end of input. */
+    parseDocument() {
+        const value = this.parseValue();
+        if (this.peek().kind !== 'eof')
+            this.fail('Expected end of input');
+        return value;
+    }
+    parseValue() {
+        const token = this.peek();
+        switch (token.kind) {
+            case '{':
+                return this.parseDict();
+            case '(':
+                return this.parseArray();
+            case 'string':
+                return this.next().value;
+            default:
+                return this.fail('Expected a value');
+        }
+    }
+    parseDict() {
+        this.expect('{');
+        const dict = {};
+        while (this.peek().kind !== '}') {
+            if (this.peek().kind === 'eof')
+                this.fail('Unterminated dictionary');
+            const key = this.expect('string').value;
+            this.expect('=');
+            dict[key] = this.parseValue();
+            // The `;` after an entry is required by Xcode but we accept a missing one before `}`.
+            if (this.peek().kind === ';')
+                this.next();
+            else if (this.peek().kind === 'eof')
+                this.fail('Unterminated dictionary');
+            else if (this.peek().kind !== '}')
+                this.fail('Expected ; after dictionary entry');
+        }
+        this.expect('}');
+        return dict;
+    }
+    parseArray() {
+        this.expect('(');
+        const items = [];
+        while (this.peek().kind !== ')') {
+            if (this.peek().kind === 'eof')
+                this.fail('Unterminated array');
+            items.push(this.parseValue());
+            // Commas separate items; a trailing comma is the norm. A missing comma is
+            // tolerated since values are self-delimiting.
+            if (this.peek().kind === ',')
+                this.next();
+        }
+        this.expect(')');
+        return items;
+    }
+}
+/**
+ * Parses any old-style property list text into its value tree. `parsePbxproj`
+ * is the usual entry point; this one is handy for fragments and tests.
+ */
+export function parseOldStylePlist(text) {
+    return new Parser(text, tokenizePbxproj(text)).parseDocument();
+}
+/** Parses the text of a `project.pbxproj` file into its raw object graph. */
+export function parsePbxproj(text) {
+    const value = parseOldStylePlist(text);
+    if (!isDict(value))
+        throw new Error('project.pbxproj: top-level value is not a dictionary');
+    const objectsValue = value['objects'];
+    if (!isDict(objectsValue))
+        throw new Error('project.pbxproj: missing `objects` dictionary');
+    const objects = {};
+    for (const [id, object] of Object.entries(objectsValue)) {
+        if (!isDict(object) || typeof object['isa'] !== 'string') {
+            throw new Error(`project.pbxproj: object ${id} has no isa`);
+        }
+        objects[id] = object;
+    }
+    const rootObject = value['rootObject'];
+    if (typeof rootObject !== 'string')
+        throw new Error('project.pbxproj: missing `rootObject`');
+    return {
+        archiveVersion: toInteger(value['archiveVersion'], 1),
+        objectVersion: toInteger(value['objectVersion'], 0),
+        rootObject,
+        objects,
+    };
+}
+export function isDict(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function toInteger(value, fallback) {
+    if (typeof value !== 'string')
+        return fallback;
+    const n = Number.parseInt(value, 10);
+    return Number.isNaN(n) ? fallback : n;
+}

package/dist/plist.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal reader for XML property lists (`Info.plist`).
+ *
+ * Only what the project reader needs: the top-level `<dict>` with string,
+ * integer, real, boolean, date, data, array and nested dict values. Binary
+ * plists (`bplist00`) and the old-style ASCII format are not handled here;
+ * `parseXmlPlist` returns `undefined` for anything it cannot read, and the
+ * caller treats that as "no Info.plist values available".
+ */
+export type PlistValue = string | number | boolean | PlistValue[] | PlistDict;
+export interface PlistDict {
+    [key: string]: PlistValue;
+}
+/** Parses an XML plist. Returns `undefined` when the text is not an XML plist. */
+export declare function parseXmlPlist(text: string): PlistValue | undefined;

package/dist/plist.js

@@ -0,0 +1,147 @@
+/**
+ * Minimal reader for XML property lists (`Info.plist`).
+ *
+ * Only what the project reader needs: the top-level `<dict>` with string,
+ * integer, real, boolean, date, data, array and nested dict values. Binary
+ * plists (`bplist00`) and the old-style ASCII format are not handled here;
+ * `parseXmlPlist` returns `undefined` for anything it cannot read, and the
+ * caller treats that as "no Info.plist values available".
+ */
+/** Parses an XML plist. Returns `undefined` when the text is not an XML plist. */
+export function parseXmlPlist(text) {
+    if (!/<plist[\s>]/.test(text))
+        return undefined;
+    const reader = new XmlPlistReader(text);
+    try {
+        return reader.read();
+    }
+    catch {
+        return undefined;
+    }
+}
+class XmlPlistReader {
+    text;
+    pos = 0;
+    constructor(text) {
+        this.text = text;
+    }
+    read() {
+        const plist = this.nextTag();
+        if (!plist || plist.name !== 'plist')
+            throw new Error('not a plist');
+        if (plist.selfClosing)
+            return undefined;
+        const value = this.readValue();
+        this.expectClosing('plist');
+        return value;
+    }
+    /** Reads the next opening tag (skipping the prolog, DOCTYPE, comments and whitespace). */
+    nextTag() {
+        for (;;) {
+            const lt = this.text.indexOf('<', this.pos);
+            if (lt < 0)
+                return undefined;
+            if (this.text.startsWith('<?', lt)) {
+                this.pos = this.text.indexOf('?>', lt) + 2;
+                continue;
+            }
+            if (this.text.startsWith('<!--', lt)) {
+                this.pos = this.text.indexOf('-->', lt) + 3;
+                continue;
+            }
+            if (this.text.startsWith('<!', lt)) {
+                this.pos = this.text.indexOf('>', lt) + 1;
+                continue;
+            }
+            const gt = this.text.indexOf('>', lt);
+            if (gt < 0)
+                throw new Error('unterminated tag');
+            let inside = this.text.slice(lt + 1, gt).trim();
+            const selfClosing = inside.endsWith('/');
+            if (selfClosing)
+                inside = inside.slice(0, -1).trim();
+            const name = inside.split(/\s/, 1)[0] ?? '';
+            this.pos = gt + 1;
+            return { name, selfClosing, end: gt + 1 };
+        }
+    }
+    /** Peeks: is the next tag the closing `</name>`? Consumes it when so. */
+    atClosing(name) {
+        const rest = this.text.slice(this.pos);
+        const match = /^\s*<\/\s*([^\s>]+)\s*>/.exec(rest);
+        if (!match || match[1] !== name)
+            return false;
+        this.pos += match[0].length;
+        return true;
+    }
+    expectClosing(name) {
+        if (!this.atClosing(name))
+            throw new Error(`expected </${name}>`);
+    }
+    /** Reads the text content up to `</name>` (entities decoded). */
+    readText(name) {
+        const close = this.text.indexOf(`</${name}>`, this.pos);
+        if (close < 0)
+            throw new Error(`expected </${name}>`);
+        const raw = this.text.slice(this.pos, close);
+        this.pos = close + name.length + 3;
+        return decodeEntities(raw);
+    }
+    readValue() {
+        const tag = this.nextTag();
+        if (!tag)
+            throw new Error('expected a value');
+        switch (tag.name) {
+            case 'string':
+            case 'date':
+            case 'data':
+                return tag.selfClosing ? '' : this.readText(tag.name);
+            case 'integer':
+            case 'real':
+                return tag.selfClosing ? 0 : Number(this.readText(tag.name).trim());
+            case 'true':
+                return true;
+            case 'false':
+                return false;
+            case 'array': {
+                const items = [];
+                if (tag.selfClosing)
+                    return items;
+                while (!this.atClosing('array'))
+                    items.push(this.readValue());
+                return items;
+            }
+            case 'dict': {
+                const dict = {};
+                if (tag.selfClosing)
+                    return dict;
+                while (!this.atClosing('dict')) {
+                    const keyTag = this.nextTag();
+                    if (!keyTag || keyTag.name !== 'key')
+                        throw new Error('expected <key>');
+                    const key = keyTag.selfClosing ? '' : this.readText('key');
+                    dict[key] = this.readValue();
+                }
+                return dict;
+            }
+            default:
+                throw new Error(`unexpected <${tag.name}>`);
+        }
+    }
+}
+const NAMED_ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+};
+function decodeEntities(text) {
+    return text.replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z]+);/g, (whole, body) => {
+        if (body.startsWith('#x'))
+            return String.fromCodePoint(parseInt(body.slice(2), 16));
+        if (body.startsWith('#'))
+            return String.fromCodePoint(parseInt(body.slice(1), 10));
+        return NAMED_ENTITIES[body] ?? whole;
+    });
+}

package/dist/project.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Interprets a parsed `project.pbxproj` (pbxproj.ts) as targets with resolved
+ * file paths and build settings, so a CLI can find an iOS app's Swift sources,
+ * asset catalogs and settings without Xcode.
+ *
+ * Object graph in brief: the `rootObject` is a `PBXProject` with `targets`
+ * (`PBXNativeTarget`), a `mainGroup` (the tree of `PBXGroup`s and
+ * `PBXFileReference`s) and a `buildConfigurationList`. Each target has
+ * `buildPhases` (`PBXSourcesBuildPhase`, `PBXResourcesBuildPhase`, ...) whose
+ * `files` are `PBXBuildFile`s pointing at a `fileRef`, plus its own
+ * `buildConfigurationList` (`XCConfigurationList` -> `XCBuildConfiguration`
+ * with `buildSettings`). Xcode 16 projects can instead point a target at
+ * `PBXFileSystemSynchronizedRootGroup`s: folders whose contents are members of
+ * the target implicitly, minus per-target exception sets.
+ */
+import { type PbxprojDocument } from './pbxproj.js';
+export declare const APPLICATION_PRODUCT_TYPE = "com.apple.product-type.application";
+export interface XcodeProject {
+    /** Absolute path of the `.xcodeproj` bundle. */
+    path: string;
+    /** Directory containing the `.xcodeproj`: the source root, what `$(SRCROOT)` means. */
+    root: string;
+    objectVersion: number;
+    /** Every `PBXNativeTarget`, in project order. */
+    targets: XcodeTarget[];
+    /** The targets whose product is an application (`com.apple.product-type.application`). */
+    appTargets(): XcodeTarget[];
+}
+export interface XcodeTarget {
+    name: string;
+    /** e.g. `com.apple.product-type.application`. */
+    productType: string;
+    /** `PRODUCT_NAME` with `$(TARGET_NAME)` resolved; falls back to the target name. */
+    productName: string;
+    /** `PRODUCT_BUNDLE_IDENTIFIER`. */
+    bundleIdentifier?: string;
+    /**
+     * `INFOPLIST_KEY_CFBundleDisplayName`, else `CFBundleDisplayName` from the
+     * `INFOPLIST_FILE` when that file exists and is an XML plist.
+     */
+    displayName?: string;
+    /** `ASSETCATALOG_COMPILER_APPICON_NAME`. */
+    appIconName?: string;
+    /** `SWIFT_VERSION`. */
+    swiftVersion?: string;
+    /** `IPHONEOS_DEPLOYMENT_TARGET`. */
+    deploymentTarget?: string;
+    /**
+     * Absolute paths of the `.swift` files compiled by the target: the Sources
+     * build phase in project (navigator) order, then the files of synchronized
+     * folders (sorted).
+     */
+    sources: string[];
+    /** Absolute paths of the files and folders in the Resources build phase, in project (navigator) order. */
+    resources: string[];
+    /** Absolute paths of the `*.xcassets` among the resources and in synchronized folders. */
+    assetCatalogs: string[];
+    /** Names of the targets this one depends on (`PBXTargetDependency`). */
+    dependencies: string[];
+    /** Swift package products the target links (`XCSwiftPackageProductDependency.productName`). */
+    packageProducts: string[];
+    /**
+     * Merged build settings for a configuration: project-level settings first,
+     * target-level settings on top. `configuration` defaults to the target's
+     * default configuration: `Debug` when it has one, else the configuration
+     * list's `defaultConfigurationName`, else the first configuration.
+     * `$(TARGET_NAME)`, `$(PRODUCT_NAME)`, `$(SRCROOT)` and `$(PROJECT_DIR)` are
+     * expanded; other `$(...)` references are left as they are. An `.xcconfig`
+     * referenced by `baseConfigurationReference` is not read.
+     */
+    settings(configuration?: string): Record<string, string>;
+}
+/** Reads `<xcodeprojPath>/project.pbxproj` and interprets it. */
+export declare function readXcodeProject(xcodeprojPath: string): XcodeProject;
+/**
+ * Interprets an already parsed document as the project at `xcodeprojPath`
+ * (which need not exist; its parent directory is the source root).
+ */
+export declare function xcodeProjectFromDocument(doc: PbxprojDocument, xcodeprojPath: string): XcodeProject;
+/**
+ * Replaces `$(NAME)` and `${NAME}` for the names in `variables`; other
+ * references (`$(inherited)`, `$(SDKROOT)`, ...) are kept verbatim.
+ */
+export declare function expandVariables(value: string, variables: Record<string, string>): string;

package/dist/project.js

@@ -0,0 +1,417 @@
+/**
+ * Interprets a parsed `project.pbxproj` (pbxproj.ts) as targets with resolved
+ * file paths and build settings, so a CLI can find an iOS app's Swift sources,
+ * asset catalogs and settings without Xcode.
+ *
+ * Object graph in brief: the `rootObject` is a `PBXProject` with `targets`
+ * (`PBXNativeTarget`), a `mainGroup` (the tree of `PBXGroup`s and
+ * `PBXFileReference`s) and a `buildConfigurationList`. Each target has
+ * `buildPhases` (`PBXSourcesBuildPhase`, `PBXResourcesBuildPhase`, ...) whose
+ * `files` are `PBXBuildFile`s pointing at a `fileRef`, plus its own
+ * `buildConfigurationList` (`XCConfigurationList` -> `XCBuildConfiguration`
+ * with `buildSettings`). Xcode 16 projects can instead point a target at
+ * `PBXFileSystemSynchronizedRootGroup`s: folders whose contents are members of
+ * the target implicitly, minus per-target exception sets.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { isDict, parsePbxproj } from './pbxproj.js';
+import { parseXmlPlist } from './plist.js';
+export const APPLICATION_PRODUCT_TYPE = 'com.apple.product-type.application';
+/** Reads `<xcodeprojPath>/project.pbxproj` and interprets it. */
+export function readXcodeProject(xcodeprojPath) {
+    const absolute = path.resolve(xcodeprojPath);
+    const text = fs.readFileSync(path.join(absolute, 'project.pbxproj'), 'utf8');
+    return xcodeProjectFromDocument(parsePbxproj(text), absolute);
+}
+/**
+ * Interprets an already parsed document as the project at `xcodeprojPath`
+ * (which need not exist; its parent directory is the source root).
+ */
+export function xcodeProjectFromDocument(doc, xcodeprojPath) {
+    return new ProjectReader(doc, path.resolve(xcodeprojPath)).read();
+}
+// ----- Field access helpers -------------------------------------------------
+function str(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** The string items of an array value (anything else yields no items). */
+function strings(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+/** A build setting as one string: arrays (`GCC_PREPROCESSOR_DEFINITIONS`) are space-joined. */
+function settingString(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return strings(value).join(' ');
+    return undefined;
+}
+const SYNCHRONIZED_GROUP_ISAS = new Set(['PBXFileSystemSynchronizedRootGroup']);
+const GROUP_ISAS = new Set(['PBXGroup', 'PBXVariantGroup', 'XCVersionGroup', ...SYNCHRONIZED_GROUP_ISAS]);
+// ----- Reader -----------------------------------------------------------------
+class ProjectReader {
+    doc;
+    xcodeprojPath;
+    objects;
+    project;
+    /** Source root: the directory containing the `.xcodeproj`. */
+    root;
+    /** Directory the main group resolves to: `root` plus the project's `projectDirPath` (normally empty). */
+    mainGroupDir;
+    /** Group id of every group's and file reference's parent, for `<group>`-relative paths. */
+    parentOf = new Map();
+    /**
+     * Position of every group and file reference in a depth-first walk of the main
+     * group: the order the Xcode navigator shows. Build phases list their files
+     * in creation order, which is meaningless, so we sort them by this instead.
+     */
+    navigatorIndex = new Map();
+    resolvedPaths = new Map();
+    constructor(doc, xcodeprojPath) {
+        this.doc = doc;
+        this.xcodeprojPath = xcodeprojPath;
+        this.objects = doc.objects;
+        const project = this.objects[doc.rootObject];
+        if (!project || project.isa !== 'PBXProject') {
+            throw new Error(`project.pbxproj: rootObject ${doc.rootObject} is not a PBXProject`);
+        }
+        this.project = project;
+        this.root = path.dirname(this.xcodeprojPath);
+        this.mainGroupDir = path.resolve(this.root, str(project['projectDirPath']) ?? '');
+        for (const [id, object] of Object.entries(this.objects)) {
+            if (!GROUP_ISAS.has(object.isa))
+                continue;
+            for (const child of strings(object['children']))
+                this.parentOf.set(child, id);
+        }
+        const mainGroup = str(project['mainGroup']);
+        if (mainGroup)
+            this.indexGroup(mainGroup);
+    }
+    indexGroup(id) {
+        if (this.navigatorIndex.has(id))
+            return; // cyclic or shared child
+        this.navigatorIndex.set(id, this.navigatorIndex.size);
+        const object = this.objects[id];
+        if (object && GROUP_ISAS.has(object.isa)) {
+            for (const child of strings(object['children']))
+                this.indexGroup(child);
+        }
+    }
+    read() {
+        const targets = [];
+        for (const id of strings(this.project['targets'])) {
+            const target = this.objects[id];
+            if (target?.isa === 'PBXNativeTarget')
+                targets.push(this.readTarget(id, target));
+        }
+        return {
+            path: this.xcodeprojPath,
+            root: this.root,
+            objectVersion: this.doc.objectVersion,
+            targets,
+            appTargets: () => targets.filter((target) => target.productType === APPLICATION_PRODUCT_TYPE),
+        };
+    }
+    // --- Paths ---
+    /**
+     * Absolute path of a file reference or group, following `sourceTree`:
+     * `<group>` is relative to the parent group's directory, `SOURCE_ROOT` to the
+     * source root, `<absolute>` is absolute; anything else (`BUILT_PRODUCTS_DIR`,
+     * `SDKROOT`, `DEVELOPER_DIR`) falls back to the source root. Groups without a
+     * `path` resolve to their parent's directory.
+     */
+    resolvePath(id) {
+        if (this.resolvedPaths.has(id))
+            return this.resolvedPaths.get(id);
+        this.resolvedPaths.set(id, undefined); // guards against cyclic groups
+        const object = this.objects[id];
+        if (!object)
+            return undefined;
+        const relative = str(object['path']);
+        let base;
+        switch (str(object['sourceTree']) ?? '<group>') {
+            case '<group>': {
+                const parent = this.parentOf.get(id);
+                base = (parent ? this.resolvePath(parent) : undefined) ?? this.mainGroupDir;
+                break;
+            }
+            case '<absolute>':
+                base = '/';
+                break;
+            case 'SOURCE_ROOT':
+            default:
+                base = this.root;
+                break;
+        }
+        const resolved = relative ? path.resolve(base, relative) : base;
+        this.resolvedPaths.set(id, resolved);
+        return resolved;
+    }
+    /**
+     * Absolute paths of the files a build phase's entry refers to. A
+     * `PBXVariantGroup` (localized resources) contributes each of its variants.
+     */
+    buildFilePaths(buildFileId) {
+        const buildFile = this.objects[buildFileId];
+        const fileRef = str(buildFile?.['fileRef']);
+        if (!fileRef)
+            return [];
+        const ref = this.objects[fileRef];
+        if (!ref)
+            return [];
+        if (ref.isa === 'PBXVariantGroup') {
+            return strings(ref['children'])
+                .map((child) => this.resolvePath(child))
+                .filter((p) => p !== undefined);
+        }
+        const resolved = this.resolvePath(fileRef);
+        return resolved ? [resolved] : [];
+    }
+    /** The files of the target's build phases with the given `isa`, in navigator order. */
+    buildPhaseFiles(target, isa) {
+        const buildFileIds = [];
+        for (const phaseId of strings(target['buildPhases'])) {
+            const phase = this.objects[phaseId];
+            if (phase?.isa === isa)
+                buildFileIds.push(...strings(phase['files']));
+        }
+        const position = (buildFileId) => {
+            const fileRef = str(this.objects[buildFileId]?.['fileRef']);
+            return (fileRef ? this.navigatorIndex.get(fileRef) : undefined) ?? Number.MAX_SAFE_INTEGER;
+        };
+        return buildFileIds
+            .map((id, order) => ({ id, order, position: position(id) }))
+            .sort((a, b) => a.position - b.position || a.order - b.order)
+            .flatMap((entry) => this.buildFilePaths(entry.id));
+    }
+    // --- Synchronized folders (Xcode 16) ---
+    /**
+     * The `.swift` files and `.xcassets` folders under the target's synchronized
+     * folders, read from disk (sorted, recursive), minus the target's membership
+     * exceptions. A folder missing on disk contributes nothing.
+     */
+    synchronizedMembers(targetId, target) {
+        const sources = [];
+        const assetCatalogs = [];
+        for (const groupId of strings(target['fileSystemSynchronizedGroups'])) {
+            const group = this.objects[groupId];
+            if (!group || !SYNCHRONIZED_GROUP_ISAS.has(group.isa))
+                continue;
+            const dir = this.resolvePath(groupId);
+            if (!dir)
+                continue;
+            const excluded = new Set();
+            for (const exceptionId of strings(group['exceptions'])) {
+                const exceptions = this.objects[exceptionId];
+                if (exceptions?.isa !== 'PBXFileSystemSynchronizedBuildFileExceptionSet')
+                    continue;
+                if (str(exceptions['target']) !== targetId)
+                    continue;
+                for (const relative of strings(exceptions['membershipExceptions']))
+                    excluded.add(path.resolve(dir, relative));
+            }
+            walkSynchronizedFolder(dir, (entry) => {
+                if (excluded.has(entry))
+                    return false;
+                if (entry.endsWith('.swift'))
+                    sources.push(entry);
+                else if (entry.endsWith('.xcassets'))
+                    assetCatalogs.push(entry);
+                return true;
+            });
+        }
+        return { sources, assetCatalogs };
+    }
+    // --- Build settings ---
+    configurations(listId) {
+        const list = listId ? this.objects[listId] : undefined;
+        if (list?.isa !== 'XCConfigurationList')
+            return [];
+        return strings(list['buildConfigurations'])
+            .map((id) => this.objects[id])
+            .filter((config) => config?.isa === 'XCBuildConfiguration');
+    }
+    defaultConfigurationName(target) {
+        const listId = str(target['buildConfigurationList']);
+        const names = this.configurations(listId).map((config) => str(config['name']));
+        if (names.includes('Debug'))
+            return 'Debug';
+        const list = listId ? this.objects[listId] : undefined;
+        return str(list?.['defaultConfigurationName']) ?? names[0];
+    }
+    /** The `buildSettings` of the configuration named `name` in a configuration list. */
+    buildSettings(listId, name) {
+        const config = this.configurations(listId).find((candidate) => str(candidate['name']) === name);
+        const settings = config?.['buildSettings'];
+        return isDict(settings) ? settings : {};
+    }
+    /** Project-level then target-level settings for a configuration, as raw strings. */
+    rawSettings(target, configuration) {
+        const merged = {};
+        const layers = [
+            this.buildSettings(str(this.project['buildConfigurationList']), configuration),
+            this.buildSettings(str(target['buildConfigurationList']), configuration),
+        ];
+        for (const layer of layers) {
+            for (const [key, value] of Object.entries(layer)) {
+                const text = settingString(value);
+                if (text !== undefined)
+                    merged[key] = text;
+            }
+        }
+        return merged;
+    }
+    /**
+     * Expands the variables this package knows about in every value. `PRODUCT_NAME`
+     * is expanded first (with `$(TARGET_NAME)` only) because the other values may
+     * refer to it.
+     */
+    expandSettings(targetName, raw) {
+        const base = {
+            TARGET_NAME: targetName,
+            SRCROOT: this.root,
+            PROJECT_DIR: this.root,
+        };
+        const productName = expandVariables(raw['PRODUCT_NAME'] ?? '$(TARGET_NAME)', base) || targetName;
+        const variables = { ...base, PRODUCT_NAME: productName };
+        const settings = {};
+        for (const [key, value] of Object.entries(raw))
+            settings[key] = expandVariables(value, variables);
+        return settings;
+    }
+    // --- Targets ---
+    readTarget(targetId, target) {
+        const name = str(target['name']) ?? str(target['productName']) ?? targetId;
+        const defaultConfiguration = this.defaultConfigurationName(target);
+        const settingsCache = new Map();
+        const settings = (configuration = defaultConfiguration ?? '') => {
+            let result = settingsCache.get(configuration);
+            if (!result) {
+                result = this.expandSettings(name, this.rawSettings(target, configuration));
+                settingsCache.set(configuration, result);
+            }
+            return result;
+        };
+        const defaults = settings();
+        const phaseSources = this.buildPhaseFiles(target, 'PBXSourcesBuildPhase').filter((p) => p.endsWith('.swift'));
+        const resources = this.buildPhaseFiles(target, 'PBXResourcesBuildPhase');
+        const synchronized = this.synchronizedMembers(targetId, target);
+        const productName = defaults['PRODUCT_NAME'] || str(target['productName']) || name;
+        const result = {
+            name,
+            productType: str(target['productType']) ?? '',
+            productName,
+            sources: [...phaseSources, ...synchronized.sources],
+            resources,
+            assetCatalogs: [...resources.filter((p) => p.endsWith('.xcassets')), ...synchronized.assetCatalogs],
+            dependencies: this.dependencyNames(target),
+            packageProducts: this.packageProductNames(target),
+            settings,
+        };
+        const bundleIdentifier = defaults['PRODUCT_BUNDLE_IDENTIFIER'];
+        if (bundleIdentifier)
+            result.bundleIdentifier = bundleIdentifier;
+        const displayName = defaults['INFOPLIST_KEY_CFBundleDisplayName'] ?? this.infoPlistDisplayName(defaults['INFOPLIST_FILE']);
+        if (displayName)
+            result.displayName = displayName;
+        if (defaults['ASSETCATALOG_COMPILER_APPICON_NAME'])
+            result.appIconName = defaults['ASSETCATALOG_COMPILER_APPICON_NAME'];
+        if (defaults['SWIFT_VERSION'])
+            result.swiftVersion = defaults['SWIFT_VERSION'];
+        if (defaults['IPHONEOS_DEPLOYMENT_TARGET'])
+            result.deploymentTarget = defaults['IPHONEOS_DEPLOYMENT_TARGET'];
+        return result;
+    }
+    /** `CFBundleDisplayName` from an `INFOPLIST_FILE` (relative to the source root) when it is a readable XML plist. */
+    infoPlistDisplayName(infoPlistFile) {
+        if (!infoPlistFile)
+            return undefined;
+        let text;
+        try {
+            text = fs.readFileSync(path.resolve(this.root, infoPlistFile), 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+        const plist = parseXmlPlist(text);
+        if (typeof plist !== 'object' || plist === null || Array.isArray(plist))
+            return undefined;
+        const displayName = plist['CFBundleDisplayName'];
+        return typeof displayName === 'string' && displayName !== '' ? displayName : undefined;
+    }
+    /** Names of the target dependencies: the referenced target's name, else the dependency's own `name`. */
+    dependencyNames(target) {
+        const names = [];
+        for (const dependencyId of strings(target['dependencies'])) {
+            const dependency = this.objects[dependencyId];
+            if (dependency?.isa !== 'PBXTargetDependency')
+                continue;
+            const dependedId = str(dependency['target']);
+            const depended = dependedId ? this.objects[dependedId] : undefined;
+            const name = str(depended?.['name']) ?? str(dependency['name']) ?? this.packageProductName(str(dependency['productRef']));
+            if (name)
+                names.push(name);
+        }
+        return names;
+    }
+    packageProductName(productRefId) {
+        const product = productRefId ? this.objects[productRefId] : undefined;
+        return product?.isa === 'XCSwiftPackageProductDependency' ? str(product['productName']) : undefined;
+    }
+    /**
+     * Swift package products the target links: its `packageProductDependencies`,
+     * plus any `productRef` of a build file in its Frameworks phase (older projects).
+     */
+    packageProductNames(target) {
+        const names = new Set();
+        for (const id of strings(target['packageProductDependencies'])) {
+            const name = this.packageProductName(id);
+            if (name)
+                names.add(name);
+        }
+        for (const phaseId of strings(target['buildPhases'])) {
+            const phase = this.objects[phaseId];
+            if (phase?.isa !== 'PBXFrameworksBuildPhase')
+                continue;
+            for (const buildFileId of strings(phase['files'])) {
+                const name = this.packageProductName(str(this.objects[buildFileId]?.['productRef']));
+                if (name)
+                    names.add(name);
+            }
+        }
+        return [...names];
+    }
+}
+// ----- Helpers ----------------------------------------------------------------
+/**
+ * Replaces `$(NAME)` and `${NAME}` for the names in `variables`; other
+ * references (`$(inherited)`, `$(SDKROOT)`, ...) are kept verbatim.
+ */
+export function expandVariables(value, variables) {
+    return value.replace(/\$[({]([A-Za-z_][A-Za-z0-9_]*)[)}]/g, (whole, name) => variables[name] ?? whole);
+}
+/**
+ * Visits every entry under `dir` in sorted order, depth first. `visit` returns
+ * whether to descend into a directory; `.xcassets` bundles and dot-entries are
+ * never descended into. Unreadable directories are skipped.
+ */
+function walkSynchronizedFolder(dir, visit) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const full = path.join(dir, entry.name);
+        const descend = visit(full);
+        if (descend && entry.isDirectory() && !entry.name.endsWith('.xcassets'))
+            walkSynchronizedFolder(full, visit);
+    }
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@swiftbrowser/xcodeproj",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Reads Xcode projects (project.pbxproj): app targets, their Swift sources, asset catalogs and build settings. Pure TypeScript, no Xcode needed.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dabbott/SwiftBrowser.git",
+    "directory": "packages/xcodeproj"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test:unit": "vitest run",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "typescript": "^5.9.2",
+    "vitest": "^5.0.3"
+  }
+}