memorydetective 1.4.0 → 1.6.0

package/dist/runtime/prompts.js

@@ -0,0 +1,143 @@
+/**
+ * MCP Prompts surface — exposes the canonical investigation playbooks as
+ * named prompts (slash commands in clients that support them).
+ *
+ * Each prompt corresponds to a `Playbook` from `getInvestigationPlaybook`,
+ * but takes user-provided args (e.g. memgraph path, before/after pair) and
+ * fills the placeholders so the agent receives a ready-to-execute brief.
+ *
+ * Prompt names follow `investigate-*` / `verify-*` convention; surfaces in
+ * Claude Code as `/investigate-leak`, `/investigate-hangs`, etc.
+ */
+import { PLAYBOOKS } from "../tools/getInvestigationPlaybook.js";
+export const PROMPTS = [
+    {
+        name: "investigate-leak",
+        title: "Investigate a memgraph leak",
+        description: "Run the canonical 6-step memgraph-leak investigation: analyzeMemgraph → classifyCycle → reachableFromCycle → swiftSearchPattern → swiftGetSymbolDefinition → swiftFindSymbolReferences.",
+        arguments: [
+            {
+                name: "memgraphPath",
+                description: "Absolute path to the .memgraph file",
+                required: true,
+            },
+        ],
+        render: ({ memgraphPath }) => renderPlaybookPrompt(PLAYBOOKS["memgraph-leak"], {
+            path: memgraphPath,
+        }),
+    },
+    {
+        name: "investigate-hangs",
+        title: "Investigate user-visible hangs",
+        description: "Diagnose main-thread hangs from a `.trace` recorded with the Time Profiler or Hangs template.",
+        arguments: [
+            {
+                name: "tracePath",
+                description: "Absolute path to the .trace bundle",
+                required: true,
+            },
+        ],
+        render: ({ tracePath }) => renderPlaybookPrompt(PLAYBOOKS["perf-hangs"], { tracePath }),
+    },
+    {
+        name: "investigate-jank",
+        title: "Investigate UI jank / animation hitches",
+        description: "Diagnose dropped frames from a `.trace` recorded with the Animation Hitches template.",
+        arguments: [
+            {
+                name: "tracePath",
+                description: "Absolute path to the .trace bundle",
+                required: true,
+            },
+        ],
+        render: ({ tracePath }) => renderPlaybookPrompt(PLAYBOOKS["ui-jank"], { tracePath }),
+    },
+    {
+        name: "investigate-launch",
+        title: "Investigate slow app launch",
+        description: "Diagnose cold/warm launch slowness from a `.trace` recorded with the App Launch template.",
+        arguments: [
+            {
+                name: "tracePath",
+                description: "Absolute path to the .trace bundle",
+                required: true,
+            },
+        ],
+        render: ({ tracePath }) => renderPlaybookPrompt(PLAYBOOKS["app-launch-slow"], { tracePath }),
+    },
+    {
+        name: "verify-cycle-fix",
+        title: "Verify a fix closed a known cycle",
+        description: "Diff a before/after pair of `.memgraph` snapshots to confirm a fix actually closed the originally-classified cycle.",
+        arguments: [
+            {
+                name: "before",
+                description: "Path to the before-fix .memgraph",
+                required: true,
+            },
+            {
+                name: "after",
+                description: "Path to the after-fix .memgraph",
+                required: true,
+            },
+        ],
+        render: ({ before, after }) => renderPlaybookPrompt(PLAYBOOKS["verify-fix"], { before, after }),
+    },
+];
+export function findPrompt(name) {
+    return PROMPTS.find((p) => p.name === name);
+}
+/**
+ * Substitutes user-provided values into a playbook's argsTemplate slots and
+ * renders a markdown brief the agent can act on directly.
+ */
+function renderPlaybookPrompt(playbook, values) {
+    const lines = [];
+    lines.push(`Run the **${playbook.kind}** investigation playbook.`);
+    lines.push("");
+    lines.push(playbook.summary);
+    lines.push("");
+    lines.push("## User-provided values");
+    for (const [key, value] of Object.entries(values)) {
+        lines.push(`- \`${key}\`: \`${value}\``);
+    }
+    lines.push("");
+    lines.push("## Steps");
+    lines.push("");
+    for (const step of playbook.steps) {
+        const argsRendered = renderArgsTemplate(step.argsTemplate, values);
+        lines.push(`### ${step.step}. \`${step.tool}\``);
+        lines.push("");
+        lines.push(step.purpose);
+        lines.push("");
+        lines.push("```json");
+        lines.push(argsRendered);
+        lines.push("```");
+        if (step.resultGuidance) {
+            lines.push("");
+            lines.push(`> ${step.resultGuidance}`);
+        }
+        lines.push("");
+    }
+    lines.push("Execute the steps in order. After each tool call, follow any");
+    lines.push("`suggestedNextCalls` returned by the tool — they're the canonical");
+    lines.push("chain. Do not propose architectural changes before evidence.");
+    return lines.join("\n");
+}
+function renderArgsTemplate(template, values) {
+    // Substitute values where keys match — e.g. {path: "<absolute path...>"}
+    // becomes {path: "<actual user value>"} when values has matching key.
+    // For slots we don't have, leave the template placeholder so the agent
+    // can fill it from result chaining (e.g. step 2's class name).
+    const filled = {};
+    for (const [key, slot] of Object.entries(template)) {
+        if (typeof slot === "string" && values[key]) {
+            filled[key] = values[key];
+        }
+        else {
+            filled[key] = slot;
+        }
+    }
+    return JSON.stringify(filled, null, 2);
+}
+//# sourceMappingURL=prompts.js.map

package/dist/runtime/prompts.js.map

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

package/dist/runtime/resources.d.ts

@@ -0,0 +1,26 @@
+/**
+ * MCP Resources surface — exposes the cycle-pattern catalog as browsable
+ * read-only resources. Clients can list / read patterns without burning a
+ * tool call (cheaper than `classifyCycle`'s incidental output).
+ *
+ * URI shape: `memorydetective://patterns/{patternId}`
+ *
+ * Each resource body is markdown — clients render it directly in the UI.
+ */
+export interface PatternResource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: "text/markdown";
+}
+export interface PatternResourceBody {
+    uri: string;
+    mimeType: "text/markdown";
+    text: string;
+}
+/** Build the resource list shown to clients via `resources/list`. */
+export declare function listPatternResources(): PatternResource[];
+/** Resolve a pattern URI to a markdown body, or return null if unknown. */
+export declare function readPatternResource(uri: string): PatternResourceBody | null;
+export declare function patternUri(patternId: string): string;
+export declare function patternIdFromUri(uri: string): string | null;

package/dist/runtime/resources.js

@@ -0,0 +1,71 @@
+/**
+ * MCP Resources surface — exposes the cycle-pattern catalog as browsable
+ * read-only resources. Clients can list / read patterns without burning a
+ * tool call (cheaper than `classifyCycle`'s incidental output).
+ *
+ * URI shape: `memorydetective://patterns/{patternId}`
+ *
+ * Each resource body is markdown — clients render it directly in the UI.
+ */
+import { PATTERNS } from "../tools/classifyCycle.js";
+const URI_SCHEME = "memorydetective";
+const PATTERNS_HOST = "patterns";
+/** Build the resource list shown to clients via `resources/list`. */
+export function listPatternResources() {
+    return PATTERNS.map((p) => ({
+        uri: patternUri(p.id),
+        name: p.name,
+        description: oneLineDescription(p),
+        mimeType: "text/markdown",
+    }));
+}
+/** Resolve a pattern URI to a markdown body, or return null if unknown. */
+export function readPatternResource(uri) {
+    const id = patternIdFromUri(uri);
+    if (!id)
+        return null;
+    const pattern = PATTERNS.find((p) => p.id === id);
+    if (!pattern)
+        return null;
+    return {
+        uri,
+        mimeType: "text/markdown",
+        text: renderPatternMarkdown(pattern),
+    };
+}
+export function patternUri(patternId) {
+    return `${URI_SCHEME}://${PATTERNS_HOST}/${patternId}`;
+}
+export function patternIdFromUri(uri) {
+    const prefix = `${URI_SCHEME}://${PATTERNS_HOST}/`;
+    if (!uri.startsWith(prefix))
+        return null;
+    const id = uri.slice(prefix.length);
+    return id.length > 0 ? id : null;
+}
+/** Single-line summary used as the resource list description. */
+function oneLineDescription(p) {
+    // The full fixHint can be long; the list view should be scannable.
+    return p.name;
+}
+/** Markdown body for `resources/read` responses. */
+function renderPatternMarkdown(p) {
+    return [
+        `# ${p.name}`,
+        "",
+        `**Pattern ID:** \`${p.id}\``,
+        "",
+        "## Fix hint",
+        "",
+        p.fixHint,
+        "",
+        "---",
+        "",
+        "*This is a built-in pattern from the `memorydetective` cycle classifier. " +
+            "When a `.memgraph` cycle matches this pattern, `classifyCycle` returns this fix hint " +
+            "in its `primaryMatch.fixHint` field, and `verifyFix` can gate a cycle-semantic diff " +
+            `against \`expectedPatternId: "${p.id}"\`.*`,
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=resources.js.map

package/dist/runtime/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../../src/runtime/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD,MAAM,UAAU,GAAG,iBAAiB,CAAC;AACrC,MAAM,aAAa,GAAG,UAAU,CAAC;AAejC,qEAAqE;AACrE,MAAM,UAAU,oBAAoB;IAClC,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1B,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,kBAAkB,CAAC,CAAC,CAAC;QAClC,QAAQ,EAAE,eAAwB;KACnC,CAAC,CAAC,CAAC;AACN,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,MAAM,EAAE,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IACrB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO;QACL,GAAG;QACH,QAAQ,EAAE,eAAe;QACzB,IAAI,EAAE,qBAAqB,CAAC,OAAO,CAAC;KACrC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,SAAiB;IAC1C,OAAO,GAAG,UAAU,MAAM,aAAa,IAAI,SAAS,EAAE,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,MAAM,GAAG,GAAG,UAAU,MAAM,aAAa,GAAG,CAAC;IACnD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACpC,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACnC,CAAC;AAED,iEAAiE;AACjE,SAAS,kBAAkB,CAAC,CAA+B;IACzD,mEAAmE;IACnE,OAAO,CAAC,CAAC,IAAI,CAAC;AAChB,CAAC;AAED,oDAAoD;AACpD,SAAS,qBAAqB,CAAC,CAI9B;IACC,OAAO;QACL,KAAK,CAAC,CAAC,IAAI,EAAE;QACb,EAAE;QACF,qBAAqB,CAAC,CAAC,EAAE,IAAI;QAC7B,EAAE;QACF,aAAa;QACb,EAAE;QACF,CAAC,CAAC,OAAO;QACT,EAAE;QACF,KAAK;QACL,EAAE;QACF,2EAA2E;YACzE,uFAAuF;YACvF,sFAAsF;YACtF,iCAAiC,CAAC,CAAC,EAAE,OAAO;QAC9C,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/runtime/staticAnalysisHints.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Static-analysis bridge: maps each cycle pattern in the catalog to the
+ * SwiftLint rule (or other static analyzer) that *would* have caught it
+ * at parse time, OR explicitly notes when no static rule exists yet.
+ *
+ * Reinforces the differentiator: memorydetective sees the *runtime evidence*
+ * (the actual cycle in a memgraph) where compilers and linters miss it
+ * because the cycle's existence requires runtime conditions (closure
+ * actually outlives owner, AsyncSequence actually never terminates, etc.).
+ *
+ * Sources:
+ * - SwiftLint rules: https://realm.github.io/SwiftLint/rule-directory.html
+ * - SwiftLint open-but-unshipped @escaping rule (8 years old):
+ *   https://github.com/realm/SwiftLint/issues/776
+ * - Swift compiler nested-closure [weak self] warning (partial fix):
+ *   https://github.com/swiftlang/swift/issues/72391 — PR #77063
+ */
+export interface StaticAnalysisHint {
+    /** SwiftLint rule identifier, or null when no rule exists. */
+    rule: string | null;
+    /** URL to the rule docs OR the open issue tracking the gap. */
+    url: string | null;
+    /** Plain-English explanation of the relationship. */
+    explanation: string;
+}
+/** Returns the static-analysis hint for a given pattern, or null if unknown. */
+export declare function getStaticAnalysisHint(patternId: string): StaticAnalysisHint | null;
+/** All known pattern ids that have hints. Used in tests for coverage assertion. */
+export declare function knownHintPatternIds(): string[];

package/dist/runtime/staticAnalysisHints.js

@@ -0,0 +1,209 @@
+/**
+ * Static-analysis bridge: maps each cycle pattern in the catalog to the
+ * SwiftLint rule (or other static analyzer) that *would* have caught it
+ * at parse time, OR explicitly notes when no static rule exists yet.
+ *
+ * Reinforces the differentiator: memorydetective sees the *runtime evidence*
+ * (the actual cycle in a memgraph) where compilers and linters miss it
+ * because the cycle's existence requires runtime conditions (closure
+ * actually outlives owner, AsyncSequence actually never terminates, etc.).
+ *
+ * Sources:
+ * - SwiftLint rules: https://realm.github.io/SwiftLint/rule-directory.html
+ * - SwiftLint open-but-unshipped @escaping rule (8 years old):
+ *   https://github.com/realm/SwiftLint/issues/776
+ * - Swift compiler nested-closure [weak self] warning (partial fix):
+ *   https://github.com/swiftlang/swift/issues/72391 — PR #77063
+ */
+/**
+ * Pattern-id → static-analysis hint. Every pattern in `classifyCycle.PATTERNS`
+ * gets an entry — either a real rule or an explicit `null` rule with reasoning.
+ */
+const HINTS = {
+    // ─────────────────────────────────────────────────────────────────────────
+    // v1.0 core
+    // ─────────────────────────────────────────────────────────────────────────
+    "swiftui.tag-index-projection": {
+        rule: null,
+        url: null,
+        explanation: "No static rule exists. The cycle is in SwiftUI's internal observation graph (TagIndexProjection), not in the user's closure. Static analyzers don't model SwiftUI internals.",
+    },
+    "swiftui.dictstorage-weakbox-cycle": {
+        rule: null,
+        url: null,
+        explanation: "No static rule exists. SwiftUI's `_DictionaryStorage<...WeakBox<AnyLocationBase>>` is a private observation type; user code never references it directly.",
+    },
+    "swiftui.foreach-state-tap": {
+        rule: null,
+        url: null,
+        explanation: "No static rule exists. The leak appears when a tap-gesture closure captures self and ForEachState outlives the closure — neither side is detectable in isolation.",
+    },
+    "closure.viewmodel-wrapped-strong": {
+        rule: null,
+        url: "https://github.com/realm/SwiftLint/issues/776",
+        explanation: "SwiftLint has an open-but-unshipped rule for `@escaping` closure capture cycles (issue #776, open since 2017). Until that ships, this can only be caught at runtime via the memgraph.",
+    },
+    "viewcontroller.uinavigationcontroller-host": {
+        rule: null,
+        url: null,
+        explanation: "No static rule exists. The cycle requires `UIViewControllerRepresentable` plus a hosting controller plus a `dismantleUIViewController` that doesn't clear the view-controller stack — too contextual for static analysis.",
+    },
+    "combine.sink-store-self-capture": {
+        rule: "weak_self",
+        url: "https://realm.github.io/SwiftLint/weak_self.html",
+        explanation: "SwiftLint's `weak_self` rule warns on closure bodies that reference `self` without `[weak self]`. Catches the most obvious cases. Doesn't catch nested closures where only the inner one has `[weak self]` (Swift compiler issue #72391, partially fixed in PR #77063).",
+    },
+    "concurrency.task-without-weak-self": {
+        rule: "weak_self",
+        url: "https://realm.github.io/SwiftLint/weak_self.html",
+        explanation: "SwiftLint `weak_self` flags `Task { self.foo() }` without `[weak self]`. The runtime evidence is still useful when the warning is suppressed or the closure is nested.",
+    },
+    "notificationcenter.observer-strong": {
+        rule: "weak_self",
+        url: "https://realm.github.io/SwiftLint/weak_self.html",
+        explanation: "Same as `combine.sink-store-self-capture` — `weak_self` catches the closure form. Doesn't help when the observer is stored as `NSObjectProtocol` and never explicitly removed in `deinit`.",
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // v1.4 expansion
+    // ─────────────────────────────────────────────────────────────────────────
+    "timer.scheduled-target-strong": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. The leak is in the *target/selector* form of `Timer.scheduledTimer` — selector-based APIs aren't analyzable for retain semantics by SwiftLint.",
+    },
+    "displaylink.target-strong": {
+        rule: null,
+        url: null,
+        explanation: "Same as `timer.scheduled-target-strong` — selector-based target retention is opaque to static analysis.",
+    },
+    "gesture.target-strong": {
+        rule: null,
+        url: null,
+        explanation: "No static rule for `addTarget(_:action:)` retention. The closure-style `UIAction` API (iOS 14+) avoids this; promoting it would prevent the leak by construction.",
+    },
+    "kvo.observation-not-invalidated": {
+        rule: "weak_self",
+        url: "https://realm.github.io/SwiftLint/weak_self.html",
+        explanation: "`weak_self` partially helps (the change-handler closure should `[weak self]`). Doesn't catch the `token.invalidate()` omission — that requires lifecycle analysis.",
+    },
+    "urlsession.delegate-strong": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. `URLSession.init(configuration:delegate:delegateQueue:)`'s strong-delegate semantics is documented Apple behavior, not a closure-capture issue.",
+    },
+    "dispatch.source-event-handler-self": {
+        rule: "weak_self",
+        url: "https://realm.github.io/SwiftLint/weak_self.html",
+        explanation: "`weak_self` catches `setEventHandler { self.foo() }`. Doesn't catch the missing `setEventHandler {}` clear-out in `deinit`.",
+    },
+    "notificationcenter.observer-not-removed": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. The leak is the *omission* of `removeObserver(_:)` in `deinit` — static analyzers don't reason about lifecycle balance.",
+    },
+    "delegate.strong-reference": {
+        rule: "weak_delegate",
+        url: "https://realm.github.io/SwiftLint/weak_delegate.html",
+        explanation: "SwiftLint's `weak_delegate` rule warns on `var delegate: SomeProtocol?` without `weak`. Catches the canonical case directly.",
+    },
+    "swiftui.envobject-back-reference": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. `@EnvironmentObject` strong back-references to UIKit interop classes require dependency-graph analysis SwiftLint doesn't perform.",
+    },
+    "combine.assign-to-self": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. `.assign(to: \\.x, on: self)` is syntactically valid; the retention is in the Combine internals.",
+    },
+    "concurrency.task-mainactor-view": {
+        rule: "weak_self",
+        url: "https://realm.github.io/SwiftLint/weak_self.html",
+        explanation: "`weak_self` catches the closure body. Doesn't catch the SwiftUI-view-storage lifetime issue — `.task { ... }` modifier vs `Task { ... }` block can't be told apart by syntax alone.",
+    },
+    "concurrency.asyncstream-continuation-self": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. `AsyncStream` continuation retention is a runtime property — the consuming Task either terminates or it doesn't.",
+    },
+    "webkit.scriptmessage-handler-strong": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. `WKUserContentController.add(_:name:)` has documented strong-retain semantics; the cycle requires the handler to also own the WebView.",
+    },
+    "coordinator.parent-strong-back-reference": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. The Coordinator pattern's `parentCoordinator` property usually isn't named `delegate`, so `weak_delegate` doesn't fire. A custom rule could match `parent*Coordinator` properties — would be a useful SwiftLint contribution.",
+    },
+    "rxswift.disposebag-self-cycle": {
+        rule: "weak_self",
+        url: "https://realm.github.io/SwiftLint/weak_self.html",
+        explanation: "`weak_self` partially helps for explicit closures. Doesn't catch the unbound-method-reference form: `subscribe(onNext: self.handle)` — Swift auto-captures the instance strongly with no syntax cue.",
+    },
+    "realm.notificationtoken-retained": {
+        rule: "weak_self",
+        url: "https://realm.github.io/SwiftLint/weak_self.html",
+        explanation: "`weak_self` catches the observe closure. Doesn't catch the `token?.invalidate()` omission in `deinit`.",
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // v1.5 catalog completion
+    // ─────────────────────────────────────────────────────────────────────────
+    "coreanimation.animation-delegate-strong": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. `CAAnimation.delegate`'s strong-retain is Apple-documented behavior, not detectable from source. A targeted SwiftLint custom rule could flag `anim.delegate = self` patterns near `layer.add(anim, ...)` — has not been written.",
+    },
+    "coreanimation.layer-delegate-cycle": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. The leak depends on whether the layer's delegate is a UIView (auto-paired, safe) or another type (leaks). Runtime-only.",
+    },
+    "coredata.fetchedresultscontroller-delegate": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. `NSFetchedResultsController.delegate` is declared `weak` in modern bridging headers, so `weak_delegate` doesn't fire — but the change-tracker still retains via the ObjC contract. Runtime-only.",
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // v1.6 catalog expansion
+    // ─────────────────────────────────────────────────────────────────────────
+    "swiftui.observable-state-modal-leak": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. The leak depends on `@Observable` + modal presentation lifecycle interaction — too contextual for SwiftLint.",
+    },
+    "swiftui.navigationpath-stored-in-viewmodel": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. `NavigationPath` is a value type held on a class — perfectly normal syntactically. The leak is in the lifecycle of pushed elements, observable only at runtime.",
+    },
+    "concurrency.async-sequence-on-self": {
+        rule: null,
+        url: "https://forums.swift.org/t/memory-leak-issue-while-asynchronously-iterating-over-async-sequence/64584",
+        explanation: "No static rule, and `[weak self]` does NOT help here — the iteration itself holds self. Documented on Swift Forums (#64584). A future swift-format/SwiftLint rule could warn on `for await ... in <storedSeq> { /* uses self */ }` patterns.",
+    },
+    "concurrency.notificationcenter-async-observer-task": {
+        rule: null,
+        url: "https://forums.swift.org/t/asyncsequence-version-of-notifications-is-causing-memory-leaks/77257",
+        explanation: "Same as `concurrency.async-sequence-on-self` — `[weak self]` is insufficient because the iteration holds the actor isolation context. Specifically called out on Swift Forums (#77257).",
+    },
+    "swiftui.observations-closure-strong-self": {
+        rule: "weak_self",
+        url: "https://realm.github.io/SwiftLint/weak_self.html",
+        explanation: "`weak_self` catches the closure body — same shape as `Combine.sink`. The `Observations { }` API is brand-new (Swift 6.2 / Xcode 26), so most projects haven't enabled the rule for it yet.",
+    },
+    "webkit.wkscriptmessagehandler-bridge": {
+        rule: null,
+        url: null,
+        explanation: "No static rule. The 3-link cycle requires a class to both own a `WKWebView` AND conform to `WKScriptMessageHandler` — detectable at runtime via the memgraph but not via SwiftLint conformance analysis.",
+    },
+};
+/** Returns the static-analysis hint for a given pattern, or null if unknown. */
+export function getStaticAnalysisHint(patternId) {
+    return HINTS[patternId] ?? null;
+}
+/** All known pattern ids that have hints. Used in tests for coverage assertion. */
+export function knownHintPatternIds() {
+    return Object.keys(HINTS);
+}
+//# sourceMappingURL=staticAnalysisHints.js.map

package/dist/runtime/staticAnalysisHints.js.map

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

package/dist/tools/classifyCycle.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { type StaticAnalysisHint } from "../runtime/staticAnalysisHints.js";
 import type { CycleNode, LeaksReport, NextCallSuggestion } from "../types.js";
 export declare const classifyCycleSchema: z.ZodObject<{
     path: z.ZodString;
@@ -22,6 +23,12 @@ export interface PatternMatch {
     reason: string;
     /** Suggested fix direction (one-liner). */
     fixHint: string;
+    /**
+     * Optional bridge to static analysis: which SwiftLint rule (if any) would
+     * have caught this cycle at parse time, or an explicit gap notice when no
+     * rule exists. Populated for every catalog pattern.
+     */
+    staticAnalysisHint?: StaticAnalysisHint;
 }
 export interface CycleClassification {
     rootClass: string;