rea-agents 4.1.0 → 5.0.0

package/dist/domain/apple/appleBundleAnatomy.js

@@ -0,0 +1,236 @@
+import { z } from "zod";
+import { digestSchema, prefixedDigestSchema } from "../digests.js";
+const pathSchema = z.string().min(1);
+const BUNDLE_EXTENSION = /\.(?:app|appex|xpc|framework|systemextension|dext|bundle|plugin|qlgenerator|mdimporter)$/iu;
+const MACH_O_FORMATS = ["mach-o", "mach-o-universal"];
+/** One inventoried file or directory with its content identity. */
+export const appleComponentSchema = z.strictObject({
+    path: pathSchema,
+    artifact_id: prefixedDigestSchema("art"),
+    sha256: digestSchema,
+    format: z.string().min(1),
+});
+/** One application root or nested bundle classified by path convention. */
+export const appleBundleSchema = z.strictObject({
+    path: pathSchema,
+    parent_path: pathSchema.nullable(),
+    layout: z.enum(["shallow", "macos-deep", "versioned-framework"]),
+    role: z.enum([
+        "application",
+        "app-extension",
+        "xpc-service",
+        "framework",
+        "login-item",
+        "system-extension",
+        "driver-extension",
+        "plug-in",
+        "resource-bundle",
+        "bundle",
+        "helper-application",
+        "nested-application",
+    ]),
+    role_basis: z.literal("path-convention"),
+    info_plist_path: pathSchema.nullable(),
+    executable_candidates: z.array(pathSchema),
+    signing_paths: z.array(pathSchema),
+});
+/** Report whether an inventory format is a thin or universal Mach-O. */
+export const isMachOFormat = (format) => MACH_O_FORMATS.includes(format);
+/** AppleDouble metadata written beside archived files (`._name`, `__MACOSX/`). */
+export const isSidecar = (path) => {
+    const segments = path.split("/");
+    return (segments.includes("__MACOSX") || (segments.at(-1) ?? "").startsWith("._"));
+};
+export const isWithin = (path, root) => root === "." || path === root || path.startsWith(`${root}/`);
+/**
+ * Outermost iOS (`Payload/X.app`) and macOS (`X.app/Contents/…`) applications.
+ * An inventoried `.app` directory is its own root, `.`.
+ */
+export const applicationRoots = (entries, subject) => {
+    // A selected `.app` directory is the application, even when its inventory
+    // is partial or lacks Contents/; coverage and limitations describe that.
+    if (subject.format === "directory" && /\.app$/iu.test(subject.name))
+        return ["."];
+    const found = new Set();
+    for (const { path } of entries) {
+        if (isSidecar(path))
+            continue;
+        const ios = /^(Payload\/[^/]+\.app)(?:\/|$)/u.exec(path);
+        if (ios?.[1] !== undefined) {
+            found.add(ios[1]);
+            continue;
+        }
+        const segments = path.split("/");
+        const index = segments.findIndex((segment, position) => /\.app$/iu.test(segment) && segments[position + 1] === "Contents");
+        if (index >= 0)
+            found.add(segments.slice(0, index + 1).join("/"));
+    }
+    const roots = [...found];
+    return roots
+        .filter((root) => !roots.some((other) => other !== root && isWithin(root, other)))
+        .sort(compare);
+};
+export const detectBundles = (entries, roots) => {
+    const paths = new Set(roots);
+    for (const { path, kind } of entries) {
+        if (isSidecar(path))
+            continue;
+        const root = roots.find((candidate) => isWithin(path, candidate));
+        if (root === undefined)
+            continue;
+        const segments = path.split("/");
+        const start = root === "." ? 0 : root.split("/").length;
+        for (let index = start; index < segments.length; index++) {
+            const segment = segments[index] ?? "";
+            const leaf = index === segments.length - 1;
+            // A symlink or file named like a bundle has no observed contents.
+            if (BUNDLE_EXTENSION.test(segment) && (!leaf || kind === "directory"))
+                paths.add(segments.slice(0, index + 1).join("/"));
+        }
+    }
+    const tree = indexTree(entries);
+    return [...paths].sort(compare).map((path) => {
+        const layout = bundleLayout(path, tree);
+        return {
+            path,
+            parent_path: enclosingBundle(path, paths),
+            layout,
+            role: roots.includes(path) ? "application" : bundleRole(path),
+            role_basis: "path-convention",
+            info_plist_path: infoPlistPath(path, layout, tree),
+            executable_candidates: executableCandidates(path, layout, tree),
+            signing_paths: signingPaths(path, layout, tree),
+        };
+    });
+};
+const indexTree = (entries) => {
+    const children = new Map();
+    const files = new Map();
+    const directories = new Set();
+    for (const { path, kind, component } of entries) {
+        if (isSidecar(path))
+            continue;
+        if (kind === "file" && component !== undefined)
+            files.set(path, component);
+        if (kind === "directory")
+            directories.add(path);
+        const segments = path.split("/");
+        let parent = "";
+        for (const segment of segments) {
+            const names = children.get(parent) ?? new Set();
+            names.add(segment);
+            children.set(parent, names);
+            parent = joinPath(parent, segment);
+            if (parent !== path)
+                directories.add(parent);
+        }
+    }
+    return { children, files, directories };
+};
+const joinPath = (directory, name) => directory === "" ? name : `${directory}/${name}`;
+const directoryOf = (bundle) => (bundle === "." ? "" : bundle);
+const enclosingBundle = (path, bundles) => {
+    if (path === ".")
+        return null;
+    const segments = path.split("/");
+    for (let length = segments.length - 1; length > 0; length--) {
+        const candidate = segments.slice(0, length).join("/");
+        if (bundles.has(candidate))
+            return candidate;
+    }
+    return bundles.has(".") ? "." : null;
+};
+const bundleLayout = (bundle, tree) => {
+    const names = tree.children.get(directoryOf(bundle));
+    if (names?.has("Contents") === true)
+        return "macos-deep";
+    if (names?.has("Versions") === true)
+        return "versioned-framework";
+    return "shallow";
+};
+const bundleRole = (bundle) => {
+    const segments = bundle.split("/");
+    const name = (segments.at(-1) ?? "").toLowerCase();
+    const container = segments.at(-2);
+    if (name.endsWith(".appex"))
+        return "app-extension";
+    if (name.endsWith(".xpc"))
+        return "xpc-service";
+    if (name.endsWith(".framework"))
+        return "framework";
+    if (name.endsWith(".systemextension"))
+        return "system-extension";
+    if (name.endsWith(".dext"))
+        return "driver-extension";
+    if (name.endsWith(".bundle")) {
+        if (container === "PlugIns")
+            return "plug-in";
+        return container === "Resources" ? "resource-bundle" : "bundle";
+    }
+    if (!name.endsWith(".app"))
+        return "plug-in";
+    if (container === "LoginItems" && segments.at(-3) === "Library")
+        return "login-item";
+    if (container === "Helpers")
+        return "helper-application";
+    return "nested-application";
+};
+/** Files directly inside one directory; nested bundles are deeper paths. */
+const directFiles = (directory, tree) => [...(tree.children.get(directory) ?? [])]
+    .map((name) => joinPath(directory, name))
+    .filter((path) => tree.files.has(path))
+    .sort(compare);
+/** Content directories; `Versions/Current` is a symlink outside the inventory. */
+const contentDirectories = (bundle, layout, tree) => {
+    const directory = directoryOf(bundle);
+    if (layout === "macos-deep")
+        return [joinPath(directory, "Contents")];
+    if (layout === "shallow")
+        return [directory];
+    const versions = joinPath(directory, "Versions");
+    // Only real version directories count: Current is a symlink, and files
+    // such as .DS_Store are not versions.
+    return [...(tree.children.get(versions) ?? [])]
+        .filter((version) => version !== "Current")
+        .map((version) => joinPath(versions, version))
+        .filter((version) => tree.directories.has(version))
+        .sort(compare);
+};
+const infoPlistPath = (bundle, layout, tree) => {
+    const directories = contentDirectories(bundle, layout, tree);
+    // With several real versions, Versions/Current (a symlink outside the
+    // inventory) decides which plist applies, so the plist stays unknown.
+    if (directories.length !== 1)
+        return null;
+    const candidates = directories
+        .map((directory) => joinPath(directory, layout === "versioned-framework"
+        ? "Resources/Info.plist"
+        : "Info.plist"))
+        .filter((path) => tree.files.has(path));
+    return candidates.length === 1 ? (candidates[0] ?? null) : null;
+};
+const executableCandidates = (bundle, layout, tree) => contentDirectories(bundle, layout, tree)
+    .flatMap((directory) => directFiles(layout === "macos-deep" ? joinPath(directory, "MacOS") : directory, tree))
+    .filter((path) => MACH_O_FORMATS.includes(tree.files.get(path)?.format ?? ""));
+const signingPaths = (bundle, layout, tree) => contentDirectories(bundle, layout, tree)
+    .flatMap((directory) => [
+    joinPath(directory, "_CodeSignature/CodeResources"),
+    joinPath(directory, "embedded.provisionprofile"),
+    joinPath(directory, "embedded.mobileprovision"),
+])
+    .filter((path) => tree.files.has(path))
+    .sort(compare);
+/** Platforms of application roots whose layout was observed, not assumed. */
+export const platformsOf = (bundles) => [
+    ...new Set(bundles.flatMap(({ role, layout, info_plist_path: plist }) => {
+        if (role !== "application")
+            return [];
+        if (layout === "macos-deep")
+            return ["macos"];
+        // An empty or partial root has no Contents/ either; require Info.plist.
+        if (layout === "shallow" && plist !== null)
+            return ["ios"];
+        return [];
+    })),
+].sort(compare);
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;

package/dist/domain/{interfaceBuilderGraph.js → apple/interfaceBuilderGraph.js}

@@ -1,32 +1,7 @@
 import { z } from "zod";
-import { nativeInvestigationGraphSchema, nativeInvestigationTraceLimitsSchema, } from "./nativeInvestigationGraph.js";
-import { jsonValueSchema } from "./jsonValue.js";
-const recordSchema = z.record(z.string(), z.unknown());
-const objectNode = z.strictObject({
-    id: z.string().min(1),
-    kind: z.enum([
-        "view_controller",
-        "view",
-        "control",
-        "constraint",
-        "layout_guide",
-        "resource",
-        "placeholder",
-        "external_object",
-        "other",
-    ]),
-    class_name: z.string().nullable(),
-    name: z.string().min(1),
-    attributes: z.record(z.string(), jsonValueSchema),
-});
-const connection = z.strictObject({
-    id: z.string().min(1),
-    kind: z.enum(["outlet", "action", "segue", "other"]),
-    source_id: z.string().min(1),
-    destination_id: z.string().nullable(),
-    label: z.string().nullable(),
-    attributes: z.record(z.string(), jsonValueSchema),
-});
+import { firstString, parseInterfaceBuilderRecords, record, } from "./interfaceBuilderKeyedArchive.js";
+import { nativeInvestigationEdgeSchema, nativeInvestigationGraphSchema, nativeInvestigationNodeSchema, nativeInvestigationTraceLimitsSchema, } from "../native/nativeInvestigationGraph.js";
+export { parseInterfaceBuilderRecords } from "./interfaceBuilderKeyedArchive.js";
 /** One compiled Interface Builder document projected from ibtool output. */
 export const interfaceBuilderDocumentSchema = z.strictObject({
     relative_path: z.string().min(1),
@@ -43,187 +18,6 @@ export const interfaceBuilderAnalysisSchema = z.strictObject({
     graph: nativeInvestigationGraphSchema,
     limitations: z.array(z.string()),
 });
-/** Parse ibtool dictionaries or compiled keyed archives into typed records. */
-export const parseInterfaceBuilderRecords = (value) => {
-    const root = record(value);
-    const keyed = parseKeyedArchive(root);
-    if (keyed !== null)
-        return keyed;
-    const objectsRaw = record(root["com.apple.ibtool.document.objects"]);
-    const connectionsRaw = record(root["com.apple.ibtool.document.connections"]);
-    const hierarchyRaw = root["com.apple.ibtool.document.hierarchy"];
-    const classesRaw = record(root["com.apple.ibtool.document.classes"]);
-    const objects = [];
-    const connections = [];
-    let omittedConnections = 0;
-    const objectEntries = Object.entries(objectsRaw);
-    for (const [id, raw] of objectEntries.slice(0, 20_000)) {
-        const attributes = record(raw);
-        const className = firstString(attributes["customClass"], attributes["class"], attributes["isa"]);
-        const label = firstString(attributes["label"], attributes["title"], attributes["name"], className);
-        objects.push(objectNode.parse({
-            id,
-            kind: classifyObject(className),
-            class_name: className,
-            name: label ?? id,
-            attributes: jsonSafeRecord(attributes),
-        }));
-    }
-    for (const [sourceId, rawConnections] of Object.entries(connectionsRaw)) {
-        if (!Array.isArray(rawConnections))
-            continue;
-        for (const [index, raw] of rawConnections.entries()) {
-            if (connections.length >= 40_000) {
-                omittedConnections += rawConnections.length - index;
-                break;
-            }
-            const item = record(raw);
-            const type = firstString(item.type, item.connectionType) ?? "unknown";
-            const destination = firstString(item["destination-id"], item.destinationId);
-            const label = firstString(item.label, item.selector, item.identifier);
-            connections.push(connection.parse({
-                id: `${sourceId}:connection:${index}`,
-                kind: classifyConnection(type),
-                source_id: sourceId,
-                destination_id: destination,
-                label,
-                attributes: jsonSafeRecord(item),
-            }));
-        }
-    }
-    return {
-        objects,
-        connections,
-        hierarchy: Array.isArray(hierarchyRaw) ? hierarchyRaw.slice(0, 20_000) : [],
-        classes: classesRaw,
-        objectCount: objectEntries.length,
-        omittedObjects: Math.max(0, objectEntries.length - 20_000),
-        omittedConnections,
-    };
-};
-/** Project class and connection objects from an NSKeyedArchiver object table. */
-const parseKeyedArchive = (root) => {
-    if (root.$archiver !== "NSKeyedArchiver" || !Array.isArray(root.$objects))
-        return null;
-    const objectTable = root.$objects;
-    const resolve = (value, depth = 0) => {
-        if (depth > 16)
-            return null;
-        const uid = record(value).UID;
-        if (typeof uid === "number") {
-            const target = objectTable[uid];
-            const resolved = target === undefined ? null : resolve(target, depth + 1);
-            return typeof resolved === "object" &&
-                resolved !== null &&
-                !Array.isArray(resolved)
-                ? { ...resolved, archiveUID: uid }
-                : resolved;
-        }
-        if (Array.isArray(value))
-            return value.map((item) => resolve(item, depth + 1));
-        if (typeof value !== "object" || value === null)
-            return value;
-        const output = {};
-        for (const [key, child] of Object.entries(value)) {
-            if (key === "$class") {
-                const classObject = record(typeof record(child).UID === "number"
-                    ? objectTable[record(child).UID]
-                    : child);
-                output.className = firstString(classObject.$classname);
-            }
-            else
-                output[key] = resolve(child, depth + 1);
-        }
-        return output;
-    };
-    const toHierarchy = (value, depth = 0) => {
-        if (depth > 32)
-            return [];
-        if (Array.isArray(value))
-            return value.flatMap((item) => toHierarchy(item, depth + 1));
-        if (typeof value !== "object" || value === null)
-            return [];
-        const item = record(value);
-        const objectId = firstString(item.objectID, item["object-id"], item.id, typeof item.archiveUID === "number" ? String(item.archiveUID) : null);
-        const children = Object.entries(item)
-            .filter(([key]) => /(?:subviews|contentview|childviewcontrollers|children|views)$/iu.test(key))
-            .flatMap(([, child]) => toHierarchy(child, depth + 1));
-        return objectId === null ? children : [{ objectID: objectId, children }];
-    };
-    const objects = [];
-    const connections = [];
-    let objectCount = 0;
-    let omittedConnections = 0;
-    for (const [index, raw] of objectTable.entries()) {
-        if (index === 0)
-            continue;
-        const resolved = record(resolve(raw));
-        const className = firstString(resolved.className);
-        if (className === null)
-            continue;
-        objectCount += 1;
-        const fields = Object.fromEntries(Object.entries(resolved).filter(([key]) => key !== "className"));
-        const authoredId = firstString(fields.objectID, fields["object-id"]);
-        const objectId = authoredId ??
-            (typeof fields.archiveUID === "number"
-                ? String(fields.archiveUID)
-                : String(index));
-        const kind = classifyObject(className);
-        if (objects.length < 20_000)
-            objects.push(objectNode.parse({
-                id: objectId,
-                kind,
-                class_name: className,
-                name: firstString(fields.label, fields.title, fields.identifier, fields.accessibilityLabel, className) ?? `object ${String(index)}`,
-                attributes: jsonSafeRecord(fields),
-            }));
-        if (/(?:Outlet|Connection|Segue|ActionConnection|ControlConnector)/iu.test(className)) {
-            const controlAction = /ControlConnector/iu.test(className);
-            const source = firstObjectReference(controlAction ? fields.destination : fields.source, controlAction ? fields.to : fields.from, controlAction ? fields.target : fields.owner);
-            if (source === null)
-                continue;
-            const kind = controlAction ? "action" : classifyConnection(className);
-            const parsedConnection = connection.parse({
-                id: `archive:${objectId}`,
-                kind,
-                source_id: source,
-                destination_id: firstObjectReference(controlAction ? fields.source : fields.destination, controlAction ? fields.from : fields.to, controlAction ? fields.owner : fields.target),
-                label: firstString(fields.label, fields.selector, fields.identifier, fields.action),
-                attributes: jsonSafeRecord(fields),
-            });
-            if (connections.length < 40_000)
-                connections.push(parsedConnection);
-            else
-                omittedConnections += 1;
-        }
-    }
-    const top = record(root.$top);
-    const topObject = resolve(top.root ?? top.UITopLevelObjectsKey);
-    const hierarchy = toHierarchy(topObject);
-    const classes = Object.fromEntries(objectTable.flatMap((raw) => {
-        const item = record(raw);
-        const name = firstString(item.$classname);
-        return name === null
-            ? []
-            : [
-                [
-                    name,
-                    {
-                        superclasses: Array.isArray(item.$classes) ? item.$classes : [],
-                    },
-                ],
-            ];
-    }));
-    return {
-        objects,
-        connections,
-        hierarchy,
-        classes,
-        objectCount,
-        omittedObjects: Math.max(0, objectCount - 20_000),
-        omittedConnections,
-    };
-};
 /** Build the graph returned by the static Interface Builder archive decoder. */
 export const buildInterfaceBuilderAnalysis = (input) => {
     const nodes = new Map();
@@ -358,42 +152,52 @@ export const buildInterfaceBuilderAnalysis = (input) => {
         };
         let hierarchyCount = 0;
         let hierarchyTruncated = false;
-        const visitHierarchy = (value, parentId) => {
-            if (hierarchyCount >= input.limits.max_objects) {
-                truncated = true;
-                hierarchyTruncated = true;
-                return;
-            }
-            if (Array.isArray(value)) {
-                for (const child of value)
-                    visitHierarchy(child, parentId);
-                return;
-            }
-            if (typeof value !== "object" || value === null)
-                return;
-            const item = record(value);
-            const objectId = firstString(item.objectID, item["object-id"], item.id, typeof item.archiveUID === "number" ? String(item.archiveUID) : null);
-            let nextParent = parentId;
-            if (objectId !== null) {
-                const known = objectIds.has(objectId);
-                const childId = known
-                    ? objectNodeId(objectId)
-                    : `${prefix}unknown:${objectId}`;
-                if (!known &&
-                    !addNode({
-                        id: childId,
-                        kind: "unknown",
-                        name: firstString(item.label, item.name) ?? objectId,
-                        location: null,
-                        attributes: { interface_builder_object_id: objectId },
-                        evidence: evidenceFor(`hierarchy item ${objectId}`),
-                    }))
+        const visitHierarchy = (initial, initialParentId) => {
+            const pending = [{ value: initial, parentId: initialParentId }];
+            while (pending.length > 0) {
+                if (hierarchyCount >= input.limits.max_objects) {
+                    truncated = true;
                     hierarchyTruncated = true;
-                connect(`${prefix}hierarchy:${parentId}:${childId}`, parentId, childId, "contains", `hierarchy ${objectId}`);
-                nextParent = childId;
-                hierarchyCount += 1;
+                    return;
+                }
+                const entry = pending.pop();
+                if (entry === undefined)
+                    break;
+                const { value, parentId } = entry;
+                if (Array.isArray(value)) {
+                    for (let index = value.length - 1; index >= 0; index -= 1) {
+                        const child = value[index];
+                        if (child !== undefined)
+                            pending.push({ value: child, parentId });
+                    }
+                    continue;
+                }
+                if (typeof value !== "object" || value === null)
+                    continue;
+                const item = record(value);
+                const objectId = firstString(item.objectID, item["object-id"], item.id, typeof item.archiveUID === "number" ? String(item.archiveUID) : null);
+                let nextParent = parentId;
+                if (objectId !== null) {
+                    const known = objectIds.has(objectId);
+                    const childId = known
+                        ? objectNodeId(objectId)
+                        : `${prefix}unknown:${objectId}`;
+                    if (!known &&
+                        !addNode({
+                            id: childId,
+                            kind: "unknown",
+                            name: firstString(item.label, item.name) ?? objectId,
+                            location: null,
+                            attributes: { interface_builder_object_id: objectId },
+                            evidence: evidenceFor(`hierarchy item ${objectId}`),
+                        }))
+                        hierarchyTruncated = true;
+                    connect(`${prefix}hierarchy:${parentId}:${childId}`, parentId, childId, "contains", `hierarchy ${objectId}`);
+                    nextParent = childId;
+                    hierarchyCount += 1;
+                }
+                pending.push({ value: item.children, parentId: nextParent });
             }
-            visitHierarchy(item.children, nextParent);
         };
         for (const hierarchy of parsed.hierarchy)
             visitHierarchy(hierarchy, rootId);
@@ -572,77 +376,6 @@ export const buildInterfaceBuilderAnalysis = (input) => {
         ],
     });
 };
-const record = (value) => recordSchema.safeParse(value).data ?? {};
-const firstString = (...values) => {
-    for (const value of values)
-        if (typeof value === "string" && value.length > 0)
-            return value;
-    return null;
-};
-const firstObjectReference = (...values) => {
-    for (const value of values) {
-        const direct = firstString(value);
-        if (direct !== null)
-            return direct;
-        const item = record(value);
-        const objectId = firstString(item.objectID, item["object-id"], item.id, item.identifier, typeof item.archiveUID === "number" ? String(item.archiveUID) : null);
-        if (objectId !== null)
-            return objectId;
-    }
-    return null;
-};
-const classifyObject = (className) => {
-    const value = className?.toLowerCase() ?? "";
-    if (value.includes("constraint"))
-        return "constraint";
-    if (value.includes("layoutguide"))
-        return "layout_guide";
-    if (value.includes("placeholder") || value.includes("firstresponder"))
-        return "placeholder";
-    if (value.includes("image") ||
-        value.includes("color") ||
-        value.includes("font"))
-        return "resource";
-    if (value.includes("external"))
-        return "external_object";
-    if (value.includes("viewcontroller") || value.includes("windowcontroller"))
-        return "view_controller";
-    if (value.includes("button") ||
-        value.includes("control") ||
-        value.includes("textfield") ||
-        value.includes("slider") ||
-        value.includes("menuitem"))
-        return "control";
-    if (value.includes("view") ||
-        value.includes("window") ||
-        value.includes("cell"))
-        return "view";
-    return "other";
-};
-const classifyConnection = (type) => {
-    const value = type.toLowerCase();
-    if (value.includes("outlet"))
-        return "outlet";
-    if (value.includes("action"))
-        return "action";
-    if (value.includes("segue"))
-        return "segue";
-    return "other";
-};
-const jsonSafeRecord = (value) => Object.fromEntries(Object.entries(value).flatMap(([key, item]) => {
-    try {
-        const serialized = JSON.stringify(item);
-        if (serialized === undefined)
-            return [];
-        const parsed = jsonValueSchema.safeParse(JSON.parse(serialized));
-        return parsed.success ? [[key, parsed.data]] : [];
-    }
-    catch (cause) {
-        // Unserializable entries are omitted from the record.
-        void cause;
-        return [];
-    }
-}));
 /** Hard limits shared by Interface Builder archive aggregation and tracing. */
 export const interfaceBuilderLimitsSchema = z.strictObject({
     max_documents: z.number().int().min(1).max(64).default(64),