@swiftbrowser/xcodeproj 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,90 @@
-# 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.models; // the Core ML models (.mlmodel, .mlpackage) it compiles
+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.packageDependencies; // the same, each with its package (URL and version rule, or local path)
+project.packages; // the project's Swift package references
+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`), `packages` (its `XCRemoteSwiftPackageReference`s, with
+  the dependency rule, and `XCLocalSwiftPackageReference`s, with the absolute
+  path; each with SwiftPM's identity, see `packageIdentity`) 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, packageIdentity, APPLICATION_PRODUCT_TYPE, type XcodeProject, type XcodeTarget, type SwiftPackageReference, type SwiftPackageRequirement, type SwiftPackageProductDependency, } 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, packageIdentity, 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;