xcodebuild-axi 0.1.6 → 0.1.8

package/dist/src/surface.d.ts

@@ -6,6 +6,20 @@
  * rather than inferred: every option `xcodebuild -help` prints is classified,
  * and `npm run coverage -- --check` fails if a new Xcode adds one this file
  * has never heard of.
+ *
+ * "Covered" is asked along four axes, because for a long time it was only
+ * asked along the first and the misses all landed on the other three:
+ *
+ * 1. **Options** — does any command reach this option at all.
+ * 2. **Reach** — does every command xcodebuild accepts it on reach it. An
+ *    option exposed on `build` and missing from `settings` is not covered for
+ *    anyone asking `settings`, and nothing used to say so.
+ * 3. **Forms and sub-surfaces** — the options behind an option: the keys of
+ *    `-exportOptionsPlist`, the arguments of `-create-xcframework`, the second
+ *    modes that `-help` documents only inside a usage line.
+ * 4. **Companion tools** — `xcresulttool`, `xccov`, `simctl`. Not xcodebuild,
+ *    so not in its headline number, but this tool wraps them and an agent that
+ *    has to shell out to one directly has dropped back down.
  */
 /**
  * The Xcode whose `xcodebuild -help` this map was written against.
@@ -18,11 +32,29 @@
  * mismatch here and merely reports one elsewhere.
  */
 export declare const AUTHORED_AGAINST = "27.0";
+/** One command that reaches a thing, and the words that reach it. */
+export interface Exposure {
+    /** The `xcodebuild-axi` command. */
+    command: string;
+    /** How it is reached, e.g. `settings --for-index`. */
+    via: string;
+}
+/** A command that could reach a thing and does not. */
+export interface Gap {
+    command: string;
+    why: string;
+}
 export type OptionCoverage = 
 /** Reachable through an xcodebuild-axi flag or command. */
 {
     status: "exposed";
-    via: string;
+    on: readonly Exposure[];
+    /** The command set this option applies to, when it is more than `on`. */
+    surface?: SurfaceName;
+    /** Commands in that set it will never reach, and why not. */
+    declined?: readonly Gap[];
+    /** Commands in that set it should reach and does not, yet. */
+    missing?: readonly Gap[];
 }
 /** The tool always sets it, so there is nothing for a caller to pass. */
  | {
@@ -34,22 +66,122 @@ export type OptionCoverage =
     status: "superseded";
     why: string;
 }
+/**
+ * Not wrapped yet. A gap being paid down, not a boundary — `from` names the
+ * command that will grow it, so the open list reads as a work plan.
+ */
+ | {
+    status: "missing";
+    why: string;
+    from?: string;
+}
 /** Deliberately not wrapped, for the stated reason. */
  | {
     status: "n/a";
     why: string;
 };
+/**
+ * The commands an option can apply to, by kind.
+ *
+ * xcodebuild's own usage lines are the authority: `-target` and `-alltargets`
+ * sit on the same line as `-showBuildSettings`, so `settings` is expected to
+ * take them; `-showdestinations` appears only on the `-scheme` lines, so
+ * `destinations` is not expected to take a target.
+ */
+export declare const BUILD_FAMILY: readonly ["build", "test", "tests", "analyze", "archive"];
+export declare const SURFACES: {
+    /** Shapes compilation, so only the commands that compile something. */
+    readonly build: readonly ["build", "test", "tests", "analyze", "archive"];
+    /** Applies to any action word, `clean` included. */
+    readonly action: readonly ["build", "test", "tests", "analyze", "archive", "clean"];
+    /** Changes what the project resolves to, which `settings` reports on. */
+    readonly resolution: readonly ["build", "test", "tests", "analyze", "archive", "clean", "settings"];
+    /** Package resolution, which `packages` drives on its own. */
+    readonly package: readonly ["build", "test", "tests", "analyze", "archive", "packages"];
+    /** Selects a scheme to act on. */
+    readonly scheme: readonly ["build", "test", "tests", "analyze", "archive", "clean", "settings", "destinations", "testplans", "packages", "localize"];
+    /** Constrains which tests are run, and so which tests are enumerated. */
+    readonly testing: readonly ["test", "tests"];
+};
+export type SurfaceName = keyof typeof SURFACES;
+/** `"settings --for-index"` -> `{ command: "settings", via: "settings --for-index" }`. */
+export declare function at(via: string): Exposure;
 export declare const OPTION_COVERAGE: Record<string, OptionCoverage>;
 /** The build actions, classified the same way. */
 export declare const ACTION_COVERAGE: Record<string, OptionCoverage>;
+/**
+ * The second forms of an option, which `-help` documents only inside a usage
+ * line or a sentence. Nothing enumerates these, so they are the easiest kind
+ * of gap to ship: `-runFirstLaunch -checkForNewerComponents` is a flag on a
+ * flag, mentioned once, in prose.
+ */
+export declare const FORM_COVERAGE: Record<string, OptionCoverage>;
+/**
+ * `-exportOptionsPlist` keys.
+ *
+ * The plist is the whole configuration surface of `-exportArchive`, and
+ * authoring one by hand is exactly the side quest `--method` exists to remove
+ * — so a key with no flag is a key that sends the agent back to writing XML.
+ */
+export declare const EXPORT_OPTION_COVERAGE: Record<string, OptionCoverage>;
+/** `-create-xcframework`'s own options, which only its `-help` prints. */
+export declare const XCFRAMEWORK_COVERAGE: Record<string, OptionCoverage>;
+/**
+ * `xcresulttool`, which owns every answer about a run that already happened.
+ *
+ * The result bundle is this tool's source of truth (see AGENTS.md), so a leaf
+ * missing here is an answer the bundle holds and the tool cannot read out —
+ * `test --diagnostics` collecting a report nothing can open, for instance.
+ */
+export declare const XCRESULT_COVERAGE: Record<string, OptionCoverage>;
+/** `xccov`, which owns coverage. */
+export declare const XCCOV_COVERAGE: Record<string, OptionCoverage>;
+/**
+ * `simctl`, which owns simulators.
+ *
+ * `sim` exists to put a destination into the state a build or test run needs,
+ * and stops there. The rest is classified so the boundary is a decision on
+ * the record rather than an omission.
+ */
+export declare const SIMCTL_COVERAGE: Record<string, OptionCoverage>;
+/** Every non-xcodebuild surface this tool wraps, for one combined number. */
+export declare const COMPANION_SURFACES: Record<string, Record<string, OptionCoverage>>;
 export interface CoverageTally {
     total: number;
     exposed: number;
     always: number;
     superseded: number;
+    missing: number;
     na: number;
     /** Reachable, handled for you, or answered better — what the README quotes. */
     covered: number;
     percent: number;
 }
 export declare function tally(map: Record<string, OptionCoverage>): CoverageTally;
+export declare function percent(part: number, whole: number): number;
+/** Every command an option applies to, whether or not it reaches it. */
+export declare function applicable(entry: OptionCoverage): string[];
+export interface ReachTally {
+    /** Command-and-option pairs that could exist. */
+    pairs: number;
+    reached: number;
+    declined: number;
+    missing: number;
+    percent: number;
+}
+/**
+ * Coverage counted per command rather than per option.
+ *
+ * The headline number asks whether an option is reachable at all; this one
+ * asks whether it is reachable from where you are standing, which is the
+ * question an agent that just got `unknown flag --target` was asking.
+ */
+export declare function reach(map: Record<string, OptionCoverage>): ReachTally;
+/** Every gap in a map, as `option` -> the commands that should reach it. */
+export declare function gaps(map: Record<string, OptionCoverage>): Array<{
+    option: string;
+    command: string;
+    why: string;
+}>;
+/** The README's one-line answer to "how do I reach this?". */
+export declare function describe(entry: OptionCoverage): string;