ios-agent-mcp 2.0.0 → 2.1.0

package/dist/resources.js

@@ -0,0 +1,222 @@
+import { realpathSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { analyzeConcurrency } from "./analyzers/concurrency.js";
+import { analyzeArchitecture } from "./analyzers/architecture.js";
+import { analyzeSwiftUI } from "./analyzers/swiftui.js";
+import { analyzeAvailability } from "./analyzers/availability.js";
+import { analyzeAppStore, analyzeProjectLevelAppStore } from "./analyzers/appstore.js";
+import { analyzeMemory } from "./analyzers/memory.js";
+import { analyzeSecurity } from "./analyzers/security.js";
+import { analyzeTesting, analyzeTestCoverage } from "./analyzers/testing.js";
+import { analyzePerformance } from "./analyzers/performance.js";
+import { sortFindings } from "./analyzers/types.js";
+import { readProjectContext, readSwiftFiles, resolveProjectRoot, summarizeProject, } from "./scan.js";
+/**
+ * Resource-backed project state.
+ *
+ * Tools are verbs the model chooses to call. Resources are nouns a client can
+ * read without being asked — so `ios://project/info` lets a client attach the
+ * project's shape to context up front, instead of the model having to think to
+ * run an analysis first.
+ *
+ * WHY THERE IS A CONFIGURED ROOT
+ *
+ * Resources are addressed by a fixed URI with no arguments, so `ios://project/…`
+ * only means something if the server knows which project it is. MCP clients
+ * already configure servers per project — `.cursor/mcp.json` lives in the
+ * repository, `claude mcp add` is run from it — so a root passed at launch fits
+ * how the server is actually deployed.
+ *
+ * WHY THERE IS NO ios://project/build-status
+ *
+ * It would have to run `xcodebuild`. That needs macOS and Xcode, and it breaks
+ * the `filesystem: read, network: none` contract that lets this package install
+ * anywhere in ~26 KB. Build and simulator state belong in the separate package
+ * that already requires a full toolchain — see ROADMAP.md.
+ */
+/**
+ * The directory `ios-agent` keeps its internal files in.
+ *
+ * Read-only here: this server never creates it. Its presence is used purely as
+ * a project-root marker, the same way git treats `.git` — which is what lets
+ * the CLI and this server agree on a root without either configuring the other.
+ */
+export const INTERNAL_DIR = ".ios-agent";
+/** How far up the tree to look. Guards against a symlink loop. */
+const MAX_ASCENT = 64;
+/**
+ * Walk up from `start` looking for a directory containing `.ios-agent/`.
+ *
+ * Returns `undefined` rather than a fallback, so the caller decides what an
+ * absent marker means. Guessing here is how a server ends up analyzing a user's
+ * home directory because it was launched from the wrong place.
+ */
+export function findProjectRootUpwards(start) {
+    let current = resolve(start);
+    for (let step = 0; step < MAX_ASCENT; step += 1) {
+        try {
+            if (statSync(join(current, INTERNAL_DIR)).isDirectory())
+                return realpathSync(current);
+        }
+        catch {
+            // Not here; keep walking.
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return undefined;
+}
+/**
+ * Resolve the project root, and say how.
+ *
+ * Order: `--project`, then `IOS_AGENT_PROJECT`, then the nearest ancestor with
+ * a `.ios-agent/` marker, then cwd. The marker step is what makes the server
+ * work when a client spawns it from a nested directory — previously that
+ * silently analyzed whatever subtree it happened to land in.
+ *
+ * The `source` travels with the root because an implicit root is unfalsifiable:
+ * an empty result looks identical whether the project has no Swift or the
+ * server is pointed somewhere else entirely.
+ */
+export function resolveRootFrom(argv, env) {
+    const flagIndex = argv.indexOf("--project");
+    if (flagIndex !== -1 && argv[flagIndex + 1]) {
+        return { root: resolve(argv[flagIndex + 1]), source: "flag" };
+    }
+    if (env.IOS_AGENT_PROJECT) {
+        return { root: resolve(env.IOS_AGENT_PROJECT), source: "environment" };
+    }
+    const cwd = resolve(env.PWD ?? process.cwd());
+    const marker = findProjectRootUpwards(cwd);
+    if (marker)
+        return { root: marker, source: "marker" };
+    return { root: cwd, source: "cwd" };
+}
+/** Resolve the project root from an explicit flag, the environment, a marker, or cwd. */
+export function projectRootFrom(argv, env) {
+    return resolveRootFrom(argv, env).root;
+}
+/**
+ * Every resource states the root it used.
+ *
+ * The root is implicit — it comes from a flag, the environment, or the working
+ * directory the client happened to spawn the server in. A reader who cannot see
+ * which of those won has no way to tell an empty project from a wrong path.
+ */
+function payload(uri, body) {
+    return {
+        uri,
+        mimeType: "application/json",
+        text: `${JSON.stringify(body, null, 2)}\n`,
+    };
+}
+function unavailable(uri, root, reason) {
+    return payload(uri, {
+        project_root: root,
+        available: false,
+        reason,
+        fix: "Launch the server with `--project /path/to/project`, set IOS_AGENT_PROJECT, or run it from a directory under one holding a `.ios-agent/` marker. MCP clients usually set this in the per-project config file.",
+    });
+}
+/** Scan once; every resource in a read is served from the same snapshot. */
+async function snapshot(root) {
+    const resolved = await resolveProjectRoot(root);
+    const [files, context] = await Promise.all([
+        readSwiftFiles(resolved),
+        readProjectContext(resolved),
+    ]);
+    return { resolved, files, context };
+}
+export async function projectInfoResource(uri, root, source) {
+    try {
+        const { resolved, files } = await snapshot(root);
+        if (files.length === 0) {
+            return unavailable(uri, resolved, "No Swift files found under this path.");
+        }
+        const summary = await summarizeProject(resolved, files);
+        return payload(uri, {
+            project_root: resolved,
+            resolved_from: source ?? "cwd",
+            available: true,
+            swift_files: summary.swiftFileCount,
+            lines: summary.lineCount,
+            deployment_target: summary.deploymentTarget,
+            swift_tools_version: summary.swiftToolsVersion,
+            ui_framework: summary.uiFramework,
+            architecture: summary.architecture,
+            // The evidence ships with the verdict. "MVVM" alone is a guess presented
+            // as a fact; the reader must be able to check it.
+            architecture_evidence: summary.architectureEvidence,
+            uses_dependency_injection: summary.usesDependencyInjection,
+            has_tests: summary.hasTests,
+            has_package_swift: summary.hasPackageSwift,
+            has_xcode_project: summary.hasXcodeProject,
+            frameworks: summary.frameworks,
+        });
+    }
+    catch (error) {
+        return unavailable(uri, root, error instanceof Error ? error.message : String(error));
+    }
+}
+export async function projectDependenciesResource(uri, root) {
+    try {
+        const { resolved, files } = await snapshot(root);
+        const summary = await summarizeProject(resolved, files);
+        return payload(uri, {
+            project_root: resolved,
+            available: true,
+            third_party: summary.dependencies,
+            // Apple frameworks are not dependencies you manage, but they are the
+            // best available signal for what the app actually does.
+            apple_frameworks: summary.frameworks,
+        });
+    }
+    catch (error) {
+        return unavailable(uri, root, error instanceof Error ? error.message : String(error));
+    }
+}
+export async function projectIssuesResource(uri, root) {
+    try {
+        const { resolved, files, context } = await snapshot(root);
+        if (files.length === 0) {
+            return unavailable(uri, resolved, "No Swift files found under this path.");
+        }
+        const categories = {
+            concurrency: files.flatMap(analyzeConcurrency),
+            architecture: files.flatMap(analyzeArchitecture),
+            swiftui: files.flatMap(analyzeSwiftUI),
+            availability: files.flatMap(analyzeAvailability),
+            memory: files.flatMap(analyzeMemory),
+            security: files.flatMap(analyzeSecurity),
+            performance: files.flatMap(analyzePerformance),
+            testing: [...analyzeTestCoverage(files), ...files.flatMap(analyzeTesting)],
+            app_store: [
+                ...analyzeProjectLevelAppStore(context),
+                ...files.flatMap((file) => analyzeAppStore(file, context)),
+            ],
+        };
+        const all = sortFindings(Object.values(categories).flat());
+        return payload(uri, {
+            project_root: resolved,
+            available: true,
+            files_checked: files.length,
+            counts: {
+                blocker: all.filter((f) => f.severity === "blocker").length,
+                serious: all.filter((f) => f.severity === "serious").length,
+                minor: all.filter((f) => f.severity === "minor").length,
+                total: all.length,
+            },
+            by_category: Object.fromEntries(Object.entries(categories).map(([name, found]) => [name, found.length])),
+            // Capped: a resource is attached to context wholesale, so an unbounded
+            // list would crowd out the conversation it is meant to inform.
+            issues: all.slice(0, 100),
+            truncated: all.length > 100 ? all.length - 100 : 0,
+        });
+    }
+    catch (error) {
+        return unavailable(uri, root, error instanceof Error ? error.message : String(error));
+    }
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"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"}

package/dist/result.d.ts

@@ -0,0 +1,203 @@
+import { z } from "zod";
+import { Finding } from "./analyzers/types.js";
+/**
+ * A 0–100 defect-density score.
+ *
+ *   penalty  = 10·blockers + 3·serious + 1·minor
+ *   capacity = filesChecked × 10
+ *   score    = clamp(0, 100, round(100 × (1 − penalty / capacity)))
+ *
+ * 100 means no findings. The denominator is file count, so the score is a
+ * *density*: adding clean files raises it, which is the intended behaviour for
+ * tracking one project over time.
+ *
+ * It is deliberately NOT comparable between projects — a UI-heavy target and a
+ * networking library have different rule surfaces. Use it as a direction of
+ * travel, and use the counts for anything that matters.
+ */
+export declare function scoreFor(findings: Finding[], filesChecked: number): number;
+export declare const issueSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    severity: z.ZodEnum<["blocker", "serious", "minor"]>;
+    rule: z.ZodString;
+    message: z.ZodString;
+    consequence: z.ZodString;
+    fix: z.ZodString;
+    doc: z.ZodString;
+    excerpt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    severity: "blocker" | "serious" | "minor";
+    file: string;
+    line: number;
+    message: string;
+    rule: string;
+    consequence: string;
+    fix: string;
+    doc: string;
+    excerpt: string;
+}, {
+    severity: "blocker" | "serious" | "minor";
+    file: string;
+    line: number;
+    message: string;
+    rule: string;
+    consequence: string;
+    fix: string;
+    doc: string;
+    excerpt: string;
+}>;
+/** The shape every review tool declares as its `outputSchema`. */
+export declare const reviewOutputShape: {
+    summary: z.ZodString;
+    score: z.ZodNumber;
+    counts: z.ZodObject<{
+        blocker: z.ZodNumber;
+        serious: z.ZodNumber;
+        minor: z.ZodNumber;
+        total: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        blocker: number;
+        serious: number;
+        minor: number;
+        total: number;
+    }, {
+        blocker: number;
+        serious: number;
+        minor: number;
+        total: number;
+    }>;
+    files_checked: z.ZodNumber;
+    issues: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        severity: z.ZodEnum<["blocker", "serious", "minor"]>;
+        rule: z.ZodString;
+        message: z.ZodString;
+        consequence: z.ZodString;
+        fix: z.ZodString;
+        doc: z.ZodString;
+        excerpt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        severity: "blocker" | "serious" | "minor";
+        file: string;
+        line: number;
+        message: string;
+        rule: string;
+        consequence: string;
+        fix: string;
+        doc: string;
+        excerpt: string;
+    }, {
+        severity: "blocker" | "serious" | "minor";
+        file: string;
+        line: number;
+        message: string;
+        rule: string;
+        consequence: string;
+        fix: string;
+        doc: string;
+        excerpt: string;
+    }>, "many">;
+    suggestions: z.ZodArray<z.ZodString, "many">;
+};
+export declare const reviewOutputSchema: z.ZodObject<{
+    summary: z.ZodString;
+    score: z.ZodNumber;
+    counts: z.ZodObject<{
+        blocker: z.ZodNumber;
+        serious: z.ZodNumber;
+        minor: z.ZodNumber;
+        total: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        blocker: number;
+        serious: number;
+        minor: number;
+        total: number;
+    }, {
+        blocker: number;
+        serious: number;
+        minor: number;
+        total: number;
+    }>;
+    files_checked: z.ZodNumber;
+    issues: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        severity: z.ZodEnum<["blocker", "serious", "minor"]>;
+        rule: z.ZodString;
+        message: z.ZodString;
+        consequence: z.ZodString;
+        fix: z.ZodString;
+        doc: z.ZodString;
+        excerpt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        severity: "blocker" | "serious" | "minor";
+        file: string;
+        line: number;
+        message: string;
+        rule: string;
+        consequence: string;
+        fix: string;
+        doc: string;
+        excerpt: string;
+    }, {
+        severity: "blocker" | "serious" | "minor";
+        file: string;
+        line: number;
+        message: string;
+        rule: string;
+        consequence: string;
+        fix: string;
+        doc: string;
+        excerpt: string;
+    }>, "many">;
+    suggestions: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    issues: {
+        severity: "blocker" | "serious" | "minor";
+        file: string;
+        line: number;
+        message: string;
+        rule: string;
+        consequence: string;
+        fix: string;
+        doc: string;
+        excerpt: string;
+    }[];
+    summary: string;
+    score: number;
+    counts: {
+        blocker: number;
+        serious: number;
+        minor: number;
+        total: number;
+    };
+    files_checked: number;
+    suggestions: string[];
+}, {
+    issues: {
+        severity: "blocker" | "serious" | "minor";
+        file: string;
+        line: number;
+        message: string;
+        rule: string;
+        consequence: string;
+        fix: string;
+        doc: string;
+        excerpt: string;
+    }[];
+    summary: string;
+    score: number;
+    counts: {
+        blocker: number;
+        serious: number;
+        minor: number;
+        total: number;
+    };
+    files_checked: number;
+    suggestions: string[];
+}>;
+export type ReviewOutput = z.infer<typeof reviewOutputSchema>;
+/** Build the structured half of a tool result. */
+export declare function buildReviewOutput(title: string, findings: Finding[], filesChecked: number): ReviewOutput;

package/dist/result.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { sortFindings } from "./analyzers/types.js";
+/**
+ * Structured tool output.
+ *
+ * Every review tool returns BOTH a markdown `content` block and this object as
+ * `structuredContent`. The markdown is for a human reading the transcript; the
+ * object is for a workflow that needs to branch on the result without parsing
+ * prose. Returning only JSON would make the transcript unreadable; returning
+ * only prose forces every consumer to regex it.
+ *
+ * Field names are snake_case because this is a wire contract, not internal API.
+ */
+/** Weights behind `score`. Stated here because a score nobody can reproduce is a vibe. */
+const SEVERITY_WEIGHT = {
+    blocker: 10,
+    serious: 3,
+    minor: 1,
+};
+/** One blocker per file scanned is the notional floor. */
+const CAPACITY_PER_FILE = 10;
+/**
+ * A 0–100 defect-density score.
+ *
+ *   penalty  = 10·blockers + 3·serious + 1·minor
+ *   capacity = filesChecked × 10
+ *   score    = clamp(0, 100, round(100 × (1 − penalty / capacity)))
+ *
+ * 100 means no findings. The denominator is file count, so the score is a
+ * *density*: adding clean files raises it, which is the intended behaviour for
+ * tracking one project over time.
+ *
+ * It is deliberately NOT comparable between projects — a UI-heavy target and a
+ * networking library have different rule surfaces. Use it as a direction of
+ * travel, and use the counts for anything that matters.
+ */
+export function scoreFor(findings, filesChecked) {
+    if (filesChecked <= 0)
+        return 100;
+    const penalty = findings.reduce((total, finding) => total + SEVERITY_WEIGHT[finding.severity], 0);
+    const capacity = filesChecked * CAPACITY_PER_FILE;
+    const score = Math.round(100 * (1 - penalty / capacity));
+    return Math.max(0, Math.min(100, score));
+}
+export const issueSchema = z.object({
+    file: z.string(),
+    line: z.number().int(),
+    severity: z.enum(["blocker", "serious", "minor"]),
+    rule: z.string(),
+    message: z.string(),
+    consequence: z.string(),
+    fix: z.string(),
+    doc: z.string(),
+    excerpt: z.string(),
+});
+/** The shape every review tool declares as its `outputSchema`. */
+export const reviewOutputShape = {
+    summary: z.string().describe("One-line plain-language result."),
+    score: z
+        .number()
+        .int()
+        .describe("0-100 defect density. 100 = no findings. penalty = 10*blockers + 3*serious + 1*minor; capacity = files*10. Comparable across runs on ONE project, not between projects."),
+    counts: z.object({
+        blocker: z.number().int(),
+        serious: z.number().int(),
+        minor: z.number().int(),
+        total: z.number().int(),
+    }),
+    files_checked: z.number().int().describe("Swift files actually scanned."),
+    issues: z.array(issueSchema).describe("Every finding, most severe first."),
+    suggestions: z
+        .array(z.string())
+        .describe("Prioritized next actions, deduplicated by rule — not a restatement of every issue's fix."),
+};
+export const reviewOutputSchema = z.object(reviewOutputShape);
+/**
+ * Collapse findings into a handful of actions.
+ *
+ * A `suggestions` array that simply repeats every issue's `fix` is noise — the
+ * issues already carry those. This groups by rule so a file with forty
+ * literal-spacing findings produces one instruction, ordered by total weight.
+ */
+function suggestionsFor(findings) {
+    if (findings.length === 0)
+        return [];
+    const byRule = new Map();
+    for (const finding of findings) {
+        const entry = byRule.get(finding.rule) ?? {
+            count: 0,
+            weight: 0,
+            fix: finding.fix,
+        };
+        entry.count += 1;
+        entry.weight += SEVERITY_WEIGHT[finding.severity];
+        byRule.set(finding.rule, entry);
+    }
+    return [...byRule.entries()]
+        .sort((a, b) => b[1].weight - a[1].weight)
+        .slice(0, 5)
+        .map(([rule, entry]) => entry.count === 1
+        ? `${rule}: ${entry.fix}`
+        : `${rule} (${entry.count} occurrences): ${entry.fix}`);
+}
+function summarize(title, counts, files) {
+    if (counts.total === 0) {
+        return `${title}: no findings across ${files} file${files === 1 ? "" : "s"}.`;
+    }
+    const parts = [];
+    if (counts.blocker > 0)
+        parts.push(`${counts.blocker} blocker`);
+    if (counts.serious > 0)
+        parts.push(`${counts.serious} serious`);
+    if (counts.minor > 0)
+        parts.push(`${counts.minor} minor`);
+    return `${title}: ${parts.join(", ")} across ${files} file${files === 1 ? "" : "s"}.`;
+}
+/** Build the structured half of a tool result. */
+export function buildReviewOutput(title, findings, filesChecked) {
+    const sorted = sortFindings(findings);
+    const counts = {
+        blocker: sorted.filter((f) => f.severity === "blocker").length,
+        serious: sorted.filter((f) => f.severity === "serious").length,
+        minor: sorted.filter((f) => f.severity === "minor").length,
+        total: sorted.length,
+    };
+    return {
+        summary: summarize(title, counts, filesChecked),
+        score: scoreFor(sorted, filesChecked),
+        counts,
+        files_checked: filesChecked,
+        issues: sorted,
+        suggestions: suggestionsFor(sorted),
+    };
+}
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"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"}

package/dist/scan.d.ts

@@ -20,6 +20,15 @@ export interface ProjectSummary {
     hasTests: boolean;
     hasPackageSwift: boolean;
     hasXcodeProject: boolean;
+    /** SwiftUI, UIKit, both, or neither — inferred from imports. */
+    uiFramework: "SwiftUI" | "UIKit" | "SwiftUI + UIKit" | "unknown";
+    /** Best-effort architecture read. Evidence is reported alongside it. */
+    architecture: string;
+    architectureEvidence: string[];
+    /** Third-party packages, from Package.swift / Podfile / project.pbxproj. */
+    dependencies: string[];
+    /** True when at least one dependency crosses an injected protocol boundary. */
+    usesDependencyInjection: boolean;
 }
 /** A structural overview of the project, independent of rule violations. */
 export declare function summarizeProject(root: string, files: SourceFile[]): Promise<ProjectSummary>;