rork-xcode 0.5.0 → 0.6.0

package/README.md

@@ -223,6 +223,7 @@ for (const [id, object] of project.objects()) {
 ### Semantics
 
 - **A view class for every kind.** Every `isa` Xcode writes has its own class, and each class declares its `isa` through a static field the view factory dispatches on. Targets of every kind, groups, variant and version groups, synchronized folders and their exception sets, every build phase kind, build rules, build files, build styles, configurations and configuration lists, file references, target dependencies, container item proxies, reference proxies, and Swift package references and products all come back typed. Kinds outside the vocabulary fall back to a generic `XcodeObject` with the same read and write access, so nothing in a document is out of reach.
+- **Isa literals type the returns.** Creation and lookup take the isa and give back the exact class for it, with no cast at the call site. `project.add(Isa.fileReference, ...)` is a `FileReference`, `target.ensureBuildPhase(Isa.copyFilesBuildPhase, ...)` is a `CopyFilesBuildPhase`, and `target.findBuildPhase(Isa.shellScriptBuildPhase)` is a `ShellScriptBuildPhase | undefined`. A dynamic string falls back to the generic view type.
 - **`is()` narrowing.** Every view class carries a static type guard for discriminating mixed objects: `if (NativeTarget.is(object))` narrows the way `instanceof` does, subclasses included. Relationships resolve typed too, from `dependency.target()` and `buildFile.productDependency()` to `configuration.buildSettings` as a live typed dictionary.
 - **Typed, open property shapes.** Known keys autocomplete (`target.properties.productType`) and the shape stays open, so keys like `INFOPLIST_KEY_*` settings remain first-class. The shapes describe well-formed documents. When reading untrusted input, use the narrowing accessors, which never trust them.
 - **Two verb families.** `add*` wires something to its owner (a dependency, a package, a framework, a synchronized folder) and is idempotent, so re-adding returns the existing wiring. `ensure*` returns a structural container, creating it when missing (a build phase, a group chain, the Products group). Both families can therefore run unconditionally in scaffold and repair flows.

package/dist/index.d.ts

@@ -234,6 +234,16 @@ declare const Isa: {
   readonly swiftPackageProductDependency: "XCSwiftPackageProductDependency";
   readonly versionGroup: "XCVersionGroup";
 };
+/**
+ * One of the `isa` names of the vocabulary, the union of the values of
+ * {@link Isa}.
+ */
+type IsaValue = (typeof Isa)[keyof typeof Isa];
+/**
+ * The `isa` names of the build phase kinds. The phase helpers on targets
+ * accept these, and the literal passed picks the phase class they return.
+ */
+type BuildPhaseIsa = typeof Isa.appleScriptBuildPhase | typeof Isa.copyFilesBuildPhase | typeof Isa.frameworksBuildPhase | typeof Isa.headersBuildPhase | typeof Isa.resourcesBuildPhase | typeof Isa.rezBuildPhase | typeof Isa.shellScriptBuildPhase | typeof Isa.sourcesBuildPhase;
 /**
  * Product type identifiers of the targets the model creates or reasons
  * about. Other product types pass through untouched.
@@ -613,18 +623,21 @@ declare class Target<Properties extends TargetProperties = TargetProperties> ext
   buildPhases(): BuildPhase[];
   /**
    * Finds the target's first build phase with the given isa, and, when
-   * `name` is provided, the given display name.
+   * `name` is provided, the given display name. An isa literal of the
+   * vocabulary types the result, so `findBuildPhase(Isa.copyFilesBuildPhase)`
+   * gives a `CopyFilesBuildPhase | undefined`.
    */
-  findBuildPhase(isa: string, name?: string): BuildPhase | undefined;
+  findBuildPhase<I extends string>(isa: I, name?: string): BuildPhaseOf<I> | undefined;
   /**
    * Returns the target's build phase with the given isa and properties,
    * creating and appending it when missing. The properties apply only on
-   * creation; an existing phase is returned as is.
+   * creation. An existing phase is returned as is, already typed as the
+   * phase class the isa names.
    *
    * The match key is the isa plus the `name` property when one is given,
    * so differently named copy-files phases coexist.
    */
-  ensureBuildPhase(isa: string, properties?: PbxprojObject): BuildPhase;
+  ensureBuildPhase<I extends BuildPhaseIsa>(isa: I, properties?: PbxprojObject): BuildPhaseOf<I>;
   /**
    * The target's shell-script phase with the given name, created with the
    * usual defaults (`/bin/sh`, empty input and output lists) when missing.
@@ -1365,17 +1378,20 @@ declare class XcodeProject {
    */
   generateId(seed: string): string;
   /**
-   * Adds an object to the document and returns its view.
+   * Adds an object to the document and returns its view. When the isa is
+   * a literal of the vocabulary, the returned view is already the exact
+   * class for it, so `add(Isa.fileReference, ...)` gives a `FileReference`
+   * with no cast at the call site.
    *
-   * @param isa The object's kind; written as the `isa` property.
+   * @param isa The object's kind, written as the `isa` property.
    * @param properties The object's remaining properties. The dictionary is
    *   stored as passed (not copied), with `isa` written first so the
    *   serialized entry leads with it.
-   * @param seed Seed for the deterministic id; defaults to the isa, which
+   * @param seed Seed for the deterministic id. Defaults to the isa, which
    *   is only sensible for singleton objects.
    * @returns The view of the created object.
    */
-  add(isa: string, properties: PbxprojObject, seed?: string): XcodeObject;
+  add<I extends string>(isa: I, properties: PbxprojObject, seed?: string): ViewOf<I>;
   /**
    * The view of the document's root `PBXProject` object.
    *
@@ -1526,6 +1542,65 @@ declare class XcodeProject {
    */
   private createView;
 }
+/**
+ * The view class for every isa of the vocabulary. The runtime registry
+ * and the {@link ViewByIsa} type are both derived from this one object,
+ * so the class an object routes to and the class its isa literal promises
+ * are always the same. The `satisfies` clause keeps the object covering
+ * the whole vocabulary, and the model tests check that every entry agrees
+ * with its class's own `isa` declaration.
+ */
+declare const VIEWS: {
+  readonly PBXAggregateTarget: typeof AggregateTarget;
+  readonly PBXAppleScriptBuildPhase: typeof AppleScriptBuildPhase;
+  readonly XCBuildConfiguration: typeof BuildConfiguration;
+  readonly PBXBuildFile: typeof BuildFile;
+  readonly PBXBuildRule: typeof BuildRule;
+  readonly PBXBuildStyle: typeof BuildStyle;
+  readonly XCConfigurationList: typeof ConfigurationList;
+  readonly PBXContainerItemProxy: typeof ContainerItemProxy;
+  readonly PBXCopyFilesBuildPhase: typeof CopyFilesBuildPhase;
+  readonly PBXFileReference: typeof FileReference;
+  readonly PBXFileSystemSynchronizedBuildFileExceptionSet: typeof BuildFileExceptionSet;
+  readonly PBXFileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet: typeof BuildPhaseMembershipExceptionSet;
+  readonly PBXFileSystemSynchronizedRootGroup: typeof SyncRootGroup;
+  readonly PBXFrameworksBuildPhase: typeof FrameworksBuildPhase;
+  readonly PBXGroup: typeof Group;
+  readonly PBXHeadersBuildPhase: typeof HeadersBuildPhase;
+  readonly PBXLegacyTarget: typeof LegacyTarget;
+  readonly XCLocalSwiftPackageReference: typeof LocalSwiftPackageReference;
+  readonly PBXNativeTarget: typeof NativeTarget;
+  readonly PBXProject: typeof RootProject;
+  readonly PBXReferenceProxy: typeof ReferenceProxy;
+  readonly XCRemoteSwiftPackageReference: typeof RemoteSwiftPackageReference;
+  readonly PBXResourcesBuildPhase: typeof ResourcesBuildPhase;
+  readonly PBXRezBuildPhase: typeof RezBuildPhase;
+  readonly PBXShellScriptBuildPhase: typeof ShellScriptBuildPhase;
+  readonly PBXSourcesBuildPhase: typeof SourcesBuildPhase;
+  readonly XCSwiftPackageProductDependency: typeof SwiftPackageProductDependency;
+  readonly PBXTargetDependency: typeof TargetDependency;
+  readonly PBXVariantGroup: typeof VariantGroup;
+  readonly XCVersionGroup: typeof VersionGroup;
+};
+/**
+ * The view class each isa of the vocabulary maps to, as a type. Derived
+ * from the same {@link VIEWS} object the runtime registry is built from,
+ * which is what lets creation and lookup helpers return the exact class
+ * for an isa literal instead of a base class the caller has to cast.
+ */
+type ViewByIsa = { [I in keyof typeof VIEWS]: InstanceType<(typeof VIEWS)[I]> };
+/**
+ * The view type an isa literal resolves to. Literals of the vocabulary
+ * give the dedicated class, and anything else gives the generic
+ * `XcodeObject`.
+ */
+type ViewOf<I extends string> = I extends keyof ViewByIsa ? ViewByIsa[I] : XcodeObject;
+/**
+ * The build phase view an isa literal resolves to. Isas outside the
+ * vocabulary give the generic `BuildPhase`, matching the view factory's
+ * suffix fallback.
+ */
+type BuildPhaseOf<I extends string> = I extends keyof ViewByIsa ? Extract<ViewByIsa[I], BuildPhase> : BuildPhase;
 //#endregion
 //#region src/model/object.d.ts
 /**
@@ -1543,10 +1618,11 @@ declare class XcodeProject {
 declare class XcodeObject<Properties extends PbxprojObject = PbxprojObject> {
   /**
    * The `isa` name this view class models. Each concrete view declares
-   * its own, and the project's view factory dispatches on it, so the
-   * class itself is the source of truth for which objects it covers.
-   * Classes that only share behavior, like this base class and the
-   * abstract target and phase bases, declare `null` and never route.
+   * its own, the factory registry routes objects of that isa to the
+   * class, and the model tests keep the registry and these declarations
+   * in agreement. Classes that only share behavior, like this base class
+   * and the abstract target and phase bases, declare `null` and never
+   * route.
    */
   static readonly isa: string | null;
   /** The project this object belongs to. */
@@ -1870,4 +1946,4 @@ declare function parseXcscheme(text: string): XcschemeDocument;
  */
 declare function generateObjectId(seed: string, existing: ReadonlySet<string>): string;
 //#endregion
-export { type AddNativeTargetOptions, AggregateTarget, type ApplePlatform, AppleScriptBuildPhase, BuildConfiguration, type BuildConfigurationProperties, BuildFile, BuildFileExceptionSet, type BuildFileProperties, BuildPhase, BuildPhaseMembershipExceptionSet, type BuildPhaseMembershipExceptionSetProperties, type BuildPhaseProperties, BuildRule, type BuildRuleProperties, type BuildSettings, BuildStyle, type BuildStyleProperties, BuildableReference, ConfigurationList, type ConfigurationListProperties, ContainerItemProxy, type ContainerItemProxyProperties, CopyFilesBuildPhase, type CopyFilesBuildPhaseProperties, CopyFilesDestination, type CreateXcschemeOptions, ExceptionSet, type ExceptionSetProperties, FileReference, type FileReferenceProperties, FrameworksBuildPhase, Group, type GroupProperties, HeadersBuildPhase, Isa, LegacyTarget, type LegacyTargetProperties, LocalSwiftPackageReference, type LocalSwiftPackageReferenceProperties, NativeTarget, type NativeTargetProperties, type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, ProductType, type ProjectIssue, type ProjectIssueKind, ReferenceProxy, type ReferenceProxyProperties, RemoteSwiftPackageReference, type RemoteSwiftPackageReferenceProperties, ResourcesBuildPhase, RezBuildPhase, RootProject, type RootProjectProperties, ShellScriptBuildPhase, type ShellScriptBuildPhaseProperties, SourcesBuildPhase, SwiftPackageProductDependency, type SwiftPackageProductDependencyProperties, SwiftPackageReference, type SwiftPackageReferenceProperties, SyncRootGroup, type SyncRootGroupProperties, Target, TargetDependency, type TargetDependencyProperties, type TargetProperties, VariantGroup, VersionGroup, type VersionGroupProperties, XcodeModelError, XcodeObject, XcodeProject, Xcscheme, XcschemeBuildError, type XcschemeComment, type XcschemeDocument, type XcschemeElement, type XcschemeNode, XcschemeParseError, buildPbxproj, buildXcscheme, createXcscheme, generateObjectId, isXcschemeElement, parsePbxproj, parseXcscheme, xcschemeElements };
+export { type AddNativeTargetOptions, AggregateTarget, type ApplePlatform, AppleScriptBuildPhase, BuildConfiguration, type BuildConfigurationProperties, BuildFile, BuildFileExceptionSet, type BuildFileProperties, BuildPhase, type BuildPhaseIsa, BuildPhaseMembershipExceptionSet, type BuildPhaseMembershipExceptionSetProperties, type BuildPhaseOf, type BuildPhaseProperties, BuildRule, type BuildRuleProperties, type BuildSettings, BuildStyle, type BuildStyleProperties, BuildableReference, ConfigurationList, type ConfigurationListProperties, ContainerItemProxy, type ContainerItemProxyProperties, CopyFilesBuildPhase, type CopyFilesBuildPhaseProperties, CopyFilesDestination, type CreateXcschemeOptions, ExceptionSet, type ExceptionSetProperties, FileReference, type FileReferenceProperties, FrameworksBuildPhase, Group, type GroupProperties, HeadersBuildPhase, Isa, type IsaValue, LegacyTarget, type LegacyTargetProperties, LocalSwiftPackageReference, type LocalSwiftPackageReferenceProperties, NativeTarget, type NativeTargetProperties, type PbxprojArray, PbxprojBuildError, type PbxprojErrorPosition, type PbxprojObject, PbxprojParseError, type PbxprojValue, ProductType, type ProjectIssue, type ProjectIssueKind, ReferenceProxy, type ReferenceProxyProperties, RemoteSwiftPackageReference, type RemoteSwiftPackageReferenceProperties, ResourcesBuildPhase, RezBuildPhase, RootProject, type RootProjectProperties, ShellScriptBuildPhase, type ShellScriptBuildPhaseProperties, SourcesBuildPhase, SwiftPackageProductDependency, type SwiftPackageProductDependencyProperties, SwiftPackageReference, type SwiftPackageReferenceProperties, SyncRootGroup, type SyncRootGroupProperties, Target, TargetDependency, type TargetDependencyProperties, type TargetProperties, VariantGroup, VersionGroup, type VersionGroupProperties, type ViewByIsa, type ViewOf, XcodeModelError, XcodeObject, XcodeProject, Xcscheme, XcschemeBuildError, type XcschemeComment, type XcschemeDocument, type XcschemeElement, type XcschemeNode, XcschemeParseError, buildPbxproj, buildXcscheme, createXcscheme, generateObjectId, isXcschemeElement, parsePbxproj, parseXcscheme, xcschemeElements };

package/dist/index.js

@@ -1033,10 +1033,11 @@ function stringItems(value) {
 var XcodeObject = class {
 	/**
 	* The `isa` name this view class models. Each concrete view declares
-	* its own, and the project's view factory dispatches on it, so the
-	* class itself is the source of truth for which objects it covers.
-	* Classes that only share behavior, like this base class and the
-	* abstract target and phase bases, declare `null` and never route.
+	* its own, the factory registry routes objects of that isa to the
+	* class, and the model tests keep the registry and these declarations
+	* in agreement. Classes that only share behavior, like this base class
+	* and the abstract target and phase bases, declare `null` and never
+	* route.
 	*/
 	static isa = null;
 	/** The project this object belongs to. */
@@ -2962,7 +2963,9 @@ var Target = class extends XcodeObject {
 	}
 	/**
 	* Finds the target's first build phase with the given isa, and, when
-	* `name` is provided, the given display name.
+	* `name` is provided, the given display name. An isa literal of the
+	* vocabulary types the result, so `findBuildPhase(Isa.copyFilesBuildPhase)`
+	* gives a `CopyFilesBuildPhase | undefined`.
 	*/
 	findBuildPhase(isa, name) {
 		return this.buildPhases().find((phase) => phase.isa === isa && (name == null || phase.name === name));
@@ -2970,7 +2973,8 @@ var Target = class extends XcodeObject {
 	/**
 	* Returns the target's build phase with the given isa and properties,
 	* creating and appending it when missing. The properties apply only on
-	* creation; an existing phase is returned as is.
+	* creation. An existing phase is returned as is, already typed as the
+	* phase class the isa names.
 	*
 	* The match key is the isa plus the `name` property when one is given,
 	* so differently named copy-files phases coexist.
@@ -3419,13 +3423,16 @@ var XcodeProject = class XcodeProject {
 		return generateObjectId(seed, new Set(Object.keys(this.objectsDictionary)));
 	}
 	/**
-	* Adds an object to the document and returns its view.
+	* Adds an object to the document and returns its view. When the isa is
+	* a literal of the vocabulary, the returned view is already the exact
+	* class for it, so `add(Isa.fileReference, ...)` gives a `FileReference`
+	* with no cast at the call site.
 	*
-	* @param isa The object's kind; written as the `isa` property.
+	* @param isa The object's kind, written as the `isa` property.
 	* @param properties The object's remaining properties. The dictionary is
 	*   stored as passed (not copied), with `isa` written first so the
 	*   serialized entry leads with it.
-	* @param seed Seed for the deterministic id; defaults to the isa, which
+	* @param seed Seed for the deterministic id. Defaults to the isa, which
 	*   is only sensible for singleton objects.
 	* @returns The view of the created object.
 	*/
@@ -3528,11 +3535,10 @@ var XcodeProject = class XcodeProject {
 			productType: options.productType
 		}, `${Isa.nativeTarget} ${options.name}`);
 		ensureArray(this.rootProject.properties, "targets").push(target.id);
-		const nativeTarget = target;
-		nativeTarget.ensureSourcesPhase();
-		nativeTarget.ensureFrameworksPhase();
-		nativeTarget.ensureResourcesPhase();
-		return nativeTarget;
+		target.ensureSourcesPhase();
+		target.ensureFrameworksPhase();
+		target.ensureResourcesPhase();
+		return target;
 	}
 	/**
 	* Finds the remote Swift package reference for a repository URL.
@@ -3736,48 +3742,49 @@ var XcodeProject = class XcodeProject {
 	}
 };
 /**
-* Every concrete view class of the object model. The registry below is
-* derived from this list, so adding a view class with its `isa` is all
-* it takes to route objects of that kind to it.
-*/
-const VIEW_CLASSES = [
-	AggregateTarget,
-	AppleScriptBuildPhase,
-	BuildConfiguration,
-	BuildFile,
-	BuildFileExceptionSet,
-	BuildPhaseMembershipExceptionSet,
-	BuildRule,
-	BuildStyle,
-	ConfigurationList,
-	ContainerItemProxy,
-	CopyFilesBuildPhase,
-	FileReference,
-	FrameworksBuildPhase,
-	Group,
-	HeadersBuildPhase,
-	LegacyTarget,
-	LocalSwiftPackageReference,
-	NativeTarget,
-	ReferenceProxy,
-	RemoteSwiftPackageReference,
-	ResourcesBuildPhase,
-	RezBuildPhase,
-	RootProject,
-	ShellScriptBuildPhase,
-	SourcesBuildPhase,
-	SwiftPackageProductDependency,
-	SyncRootGroup,
-	TargetDependency,
-	VariantGroup,
-	VersionGroup
-];
+* The view class for every isa of the vocabulary. The runtime registry
+* and the {@link ViewByIsa} type are both derived from this one object,
+* so the class an object routes to and the class its isa literal promises
+* are always the same. The `satisfies` clause keeps the object covering
+* the whole vocabulary, and the model tests check that every entry agrees
+* with its class's own `isa` declaration.
+*/
+const VIEWS = {
+	[Isa.aggregateTarget]: AggregateTarget,
+	[Isa.appleScriptBuildPhase]: AppleScriptBuildPhase,
+	[Isa.buildConfiguration]: BuildConfiguration,
+	[Isa.buildFile]: BuildFile,
+	[Isa.buildRule]: BuildRule,
+	[Isa.buildStyle]: BuildStyle,
+	[Isa.configurationList]: ConfigurationList,
+	[Isa.containerItemProxy]: ContainerItemProxy,
+	[Isa.copyFilesBuildPhase]: CopyFilesBuildPhase,
+	[Isa.fileReference]: FileReference,
+	[Isa.fileSystemSynchronizedBuildFileExceptionSet]: BuildFileExceptionSet,
+	[Isa.fileSystemSynchronizedGroupBuildPhaseMembershipExceptionSet]: BuildPhaseMembershipExceptionSet,
+	[Isa.fileSystemSynchronizedRootGroup]: SyncRootGroup,
+	[Isa.frameworksBuildPhase]: FrameworksBuildPhase,
+	[Isa.group]: Group,
+	[Isa.headersBuildPhase]: HeadersBuildPhase,
+	[Isa.legacyTarget]: LegacyTarget,
+	[Isa.localSwiftPackageReference]: LocalSwiftPackageReference,
+	[Isa.nativeTarget]: NativeTarget,
+	[Isa.project]: RootProject,
+	[Isa.referenceProxy]: ReferenceProxy,
+	[Isa.remoteSwiftPackageReference]: RemoteSwiftPackageReference,
+	[Isa.resourcesBuildPhase]: ResourcesBuildPhase,
+	[Isa.rezBuildPhase]: RezBuildPhase,
+	[Isa.shellScriptBuildPhase]: ShellScriptBuildPhase,
+	[Isa.sourcesBuildPhase]: SourcesBuildPhase,
+	[Isa.swiftPackageProductDependency]: SwiftPackageProductDependency,
+	[Isa.targetDependency]: TargetDependency,
+	[Isa.variantGroup]: VariantGroup,
+	[Isa.versionGroup]: VersionGroup
+};
 /**
-* View constructors by the isa they model, built from each class's own
-* `isa` declaration.
+* View constructors by the isa they model, in `Map` form for the factory.
 */
-const VIEW_BY_ISA = /* @__PURE__ */ new Map();
-for (const viewClass of VIEW_CLASSES) if (viewClass.isa != null) VIEW_BY_ISA.set(viewClass.isa, viewClass);
+const VIEW_BY_ISA = new Map(Object.entries(VIEWS));
 /**
 * Joins two path segments with a `/`, treating an empty prefix as the
 * project root.

package/package.json

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