feat(autofixer): per-suggestion suppression via svelte-mcp-ignore

.changeset/svelte-mcp-ignore-directive.md

@@ -0,0 +1,37 @@
+---
+'@sveltejs/mcp': minor
+---
+
+feat(autofixer): per-suggestion suppression via `svelte-mcp-ignore` directives
+
+The custom-visitor suggestions emitted by `add_autofixers_issues` (the third
+diagnostic source, separate from the Svelte compiler and ESLint passes) can now
+be silenced individually with a comment directive on the line above the
+triggering node:
+
+```svelte
+<script>
+	// svelte-mcp-ignore effect_calls_function
+	$effect(() => {
+		external_library.set(value);
+	});
+</script>
+
+<!-- svelte-mcp-ignore bind_this_attachment -->
+<canvas bind:this={canvas}></canvas>
+```
+
+Multiple codes can be listed on one directive (space-separated). Stale codes
+(no matching suggestion fired) and typos (unknown code) surface as follow-up
+"unused directive" suggestions so the comments don't quietly rot.
+
+Available codes:
+
+- `effect_calls_function`
+- `effect_assigns_state`
+- `bind_this_attachment`
+- `use_action_attachment`
+- `derived_with_function`
+- `imported_runes`
+- `runes_instead_of_store`
+- `wrong_property_access_state`

CLAUDE.md

@@ -57,6 +57,7 @@ Located in `src/lib/server/analyze/`:
 - **Autofixers** (`src/lib/mcp/autofixers.ts`): Visitor pattern implementations for code analysis
 - **Walker Utility** (`src/lib/index.ts`): Enhanced AST walking with visitor mixing capabilities
 - **Current Autofixer**: `assign_in_effect` - detects assignments to `$state` variables inside `$effect` blocks
+- **Suggestion suppression**: each custom-visitor suggestion carries a stable code (`effect_calls_function`, `bind_this_attachment`, …). Users can silence one with a `// svelte-mcp-ignore <code>` (script) or `<!-- svelte-mcp-ignore <code> -->` (markup) comment on the line above the triggering node. Stale or typo'd codes surface as follow-up "unused directive" suggestions. See `packages/mcp-server/src/mcp/autofixers/ignore-directives.ts`.
 
 ### Database Layer
 

documentation/docs/20-instructions/.generated/agents.md

@@ -17,6 +17,8 @@ After calling the list-sections tool, you MUST analyze the returned documentatio
 Analyzes Svelte code and returns issues and suggestions.
 You MUST use this tool whenever writing Svelte code before sending it to the user. Keep calling it until no issues or suggestions are returned.
 
+A confirmed false-positive suggestion can be silenced with a `// svelte-mcp-ignore <code>` (script) or `<!-- svelte-mcp-ignore <code> -->` (markup) comment on the line above the triggering node.
+
 ### 4. playground-link
 
 Generates a Svelte Playground link with the provided code.

documentation/docs/30-mcp/.generated/prompts.md

@@ -11,26 +11,28 @@ You are a Svelte expert tasked to build components and utilities for Svelte deve
 <available-docs>
 
 - title: Overview, use_cases: use title and path to estimate use case, path: ai/overview
+- title: AGENTS.md, use_cases: use title and path to estimate use case, path: ai/instructions
+- title: Overview, use_cases: use title and path to estimate use case, path: ai/mcp
 - title: Local setup, use_cases: use title and path to estimate use case, path: ai/local-setup
 - title: Remote setup, use_cases: use title and path to estimate use case, path: ai/remote-setup
 - title: Tools, use_cases: use title and path to estimate use case, path: ai/tools
 - title: Resources, use_cases: use title and path to estimate use case, path: ai/resources
 - title: Prompts, use_cases: use title and path to estimate use case, path: ai/prompts
-- title: Overview, use_cases: use title and path to estimate use case, path: ai/plugin
-- title: Subagent, use_cases: use title and path to estimate use case, path: ai/subagent
-- title: Overview, use_cases: use title and path to estimate use case, path: ai/opencode-plugin
-- title: Subagent, use_cases: use title and path to estimate use case, path: ai/opencode-subagent
+- title: CLI, use_cases: use title and path to estimate use case, path: ai/cli
 - title: Overview, use_cases: use title and path to estimate use case, path: ai/skills
+- title: Overview, use_cases: use title and path to estimate use case, path: ai/subagent
+- title: Claude Code, use_cases: use title and path to estimate use case, path: ai/claude-plugin
+- title: OpenCode, use_cases: use title and path to estimate use case, path: ai/opencode-plugin
+- title: Cursor, use_cases: use title and path to estimate use case, path: ai/cursor-plugin
 - title: Overview, use_cases: project setup, creating new svelte apps, scaffolding, cli tools, initializing projects, path: cli/overview
 - title: Frequently asked questions, use_cases: project setup, initializing new svelte projects, troubleshooting cli installation, package manager configuration, path: cli/faq
 - title: sv create, use_cases: project setup, starting new sveltekit app, initializing project, creating from playground, choosing project template, path: cli/sv-create
 - title: sv add, use_cases: project setup, adding features to existing projects, integrating tools, testing setup, styling setup, authentication, database setup, deployment adapters, path: cli/sv-add
 - title: sv check, use_cases: code quality, ci/cd pipelines, error checking, typescript projects, pre-commit hooks, finding unused css, accessibility auditing, production builds, path: cli/sv-check
 - title: sv migrate, use_cases: migration, upgrading svelte versions, upgrading sveltekit versions, modernizing codebase, svelte 3 to 4, svelte 4 to 5, sveltekit 1 to 2, adopting runes, refactoring deprecated apis, path: cli/sv-migrate
-- title: devtools-json, use_cases: development setup, chrome devtools integration, browser-based editing, local development workflow, debugging setup, path: cli/devtools-json
+- title: better-auth, use_cases: use title and path to estimate use case, path: cli/better-auth
 - title: drizzle, use_cases: database setup, sql queries, orm integration, data modeling, postgresql, mysql, sqlite, server-side data access, database migrations, type-safe queries, path: cli/drizzle
 - title: eslint, use_cases: code quality, linting, error detection, project setup, code standards, team collaboration, typescript projects, path: cli/eslint
-- title: better-auth, use_cases: use title and path to estimate use case, path: cli/better-auth
 - title: mcp, use_cases: use title and path to estimate use case, path: cli/mcp
 - title: mdsvex, use_cases: blog, content sites, markdown rendering, documentation sites, technical writing, cms integration, article pages, path: cli/mdsvex
 - title: paraglide, use_cases: internationalization, multi-language sites, i18n, translation, localization, language switching, global apps, multilingual content, path: cli/paraglide
@@ -40,7 +42,8 @@ You are a Svelte expert tasked to build components and utilities for Svelte deve
 - title: sveltekit-adapter, use_cases: deployment, production builds, hosting setup, choosing deployment platform, configuring adapters, static site generation, node server, vercel, cloudflare, netlify, path: cli/sveltekit-adapter
 - title: tailwindcss, use_cases: project setup, styling, css framework, rapid prototyping, utility-first css, design systems, responsive design, adding tailwind to svelte, path: cli/tailwind
 - title: vitest, use_cases: testing, unit tests, component testing, test setup, quality assurance, ci/cd pipelines, test-driven development, path: cli/vitest
-- title: add-on, use_cases: use title and path to estimate use case, path: cli/add-on
+- title: [create your own], use_cases: use title and path to estimate use case, path: cli/community
+- title: sv, use_cases: use title and path to estimate use case, path: cli/sv
 - title: sv-utils, use_cases: use title and path to estimate use case, path: cli/sv-utils
 - title: Introduction, use_cases: learning sveltekit, project setup, understanding framework basics, choosing between svelte and sveltekit, getting started with full-stack apps, path: kit/introduction
 - title: Creating a project, use_cases: project setup, starting new sveltekit app, initial development environment, first-time sveltekit users, scaffolding projects, path: kit/creating-a-project
@@ -198,7 +201,7 @@ You are a Svelte expert tasked to build components and utilities for Svelte deve
 
 These are the available documentation sections that `list-sections` will return, you do not need to call it again.
 
-Every time you write a Svelte component or a Svelte module you MUST invoke the `svelte-autofixer` tool providing the code. The tool will return a list of issues or suggestions. If there are any issues or suggestions you MUST fix them and call the tool again with the updated code. You MUST keep doing this until the tool returns no issues or suggestions. Only then you can return the code to the user.
+Every time you write a Svelte component or a Svelte module you MUST invoke the `svelte-autofixer` tool providing the code. The tool will return a list of issues or suggestions. If there are any issues or suggestions you MUST fix them and call the tool again with the updated code. You MUST keep doing this until the tool returns no issues or suggestions. Only then you can return the code to the user. A confirmed false-positive suggestion can be silenced with a `svelte-mcp-ignore <code>` comment on the line above; re-run the autofixer to confirm.
 
 This is the task you will work on:
 

documentation/docs/30-mcp/40-tools.md

@@ -16,6 +16,35 @@ Allows the model to get the full (and up-to-date) documentation for the requeste
 
 Uses static analysis to provide suggestions for code that your LLM generates. It can be invoked in an agentic loop by your model until all issues and suggestions are resolved.
 
+### Suppressing suggestions
+
+Heuristic suggestions can fire on intentional code. A `svelte-mcp-ignore` comment on the line above silences one (or several, space-separated). Scope matches `svelte-ignore`: the comment applies to the immediately following line. Stale or typo'd codes are reported back as follow-up suggestions.
+
+```svelte
+<script>
+	// svelte-mcp-ignore effect_calls_function
+	$effect(() => {
+		external_library.set(value);
+	});
+</script>
+
+<!-- svelte-mcp-ignore bind_this_attachment -->
+<canvas bind:this={canvas}></canvas>
+```
+
+Available codes:
+
+| Code                          | What it silences                                                                 |
+| ----------------------------- | -------------------------------------------------------------------------------- |
+| `effect_calls_function`       | "You are calling a function inside an `$effect`."                                |
+| `effect_assigns_state`        | "The stateful variable X is assigned inside an `$effect`."                       |
+| `bind_this_attachment`        | "`bind:this` can often be replaced with an `attachment`."                        |
+| `use_action_attachment`       | "Consider using an `attachment` instead of an `action`."                         |
+| `derived_with_function`       | "You are passing a function to `$derived` … use `$derived.by` instead."          |
+| `imported_runes`              | "You are importing `state` / `effect` / … from `svelte`. Runes are global."      |
+| `runes_instead_of_store`      | "You are importing `derived` / `writable` / `readable` from `svelte/store`."     |
+| `wrong_property_access_state` | "You are trying to update the stateful variable X using `set` / `update` / `$`." |
+
 ## playground-link
 
 Generates an ephemeral playground link with the generated code. It's useful when the generated code is not written to a file in your project and you want to quickly test the generated solution. The code is not stored anywhere except the URL itself (which will often, as a consequence, be quite large).

documentation/docs/40-skills/.generated/skills.md

@@ -70,6 +70,7 @@ npx @sveltejs/mcp svelte-autofixer ./Component.svelte --svelte-version 4
 1. **Uncertain about syntax?** Run `list-sections` then `get-documentation` for relevant topics
 2. **Reviewing/debugging?** Run `svelte-autofixer` on the code to detect issues
 3. **Always validate** - Run `svelte-autofixer` before finalizing any Svelte component
+4. **Confirmed false positive?** Silence one suggestion with a `// svelte-mcp-ignore <code>` (script) or `<!-- svelte-mcp-ignore <code> -->` (markup) comment on the line above, then re-run the autofixer.
 ````
 <!-- prettier-ignore-end -->
 

packages/mcp-server/src/mcp/autofixers/add-autofixers-issues.test.ts

@@ -5,8 +5,14 @@ import { base_runes } from '../../constants.js';
 const dollarless_runes = base_runes.map((r) => ({ rune: r.replace('$', '') }));
 
 function run_autofixers_on_code(code: string, desired_svelte_version = 5) {
-	const content = { issues: [], suggestions: [] };
+	const content: { issues: string[]; suggestions: string[] } = { issues: [], suggestions: [] };
 	add_autofixers_issues(content, code, desired_svelte_version);
+	// Suggestion messages carry a trailing ` [<code>]` marker
+	// since the `svelte-mcp-ignore` work — strip it here so
+	// pre-existing assertions that match the human-readable
+	// message verbatim keep working. The dedicated ignore-
+	// directive tests assert on the marker explicitly.
+	content.suggestions = content.suggestions.map((s) => s.replace(/ \[[a-z_]+\]$/, ''));
 	return content;
 }
 

packages/mcp-server/src/mcp/autofixers/add-autofixers-issues.ts

@@ -2,6 +2,7 @@ import { parse } from '../../parse/parse.js';
 import { walk } from '../../mcp/autofixers/ast/walk.js';
 import type { Node } from 'estree';
 import * as autofixers from './visitors/index.js';
+import { gather_ignore_directives, report_unused_directives } from './ignore-directives.js';
 
 export function add_autofixers_issues(
 	content: { issues: string[]; suggestions: string[] },
@@ -11,13 +12,21 @@ export function add_autofixers_issues(
 	async = false,
 ) {
 	const parsed = parse(code, filename);
+	const ignore_registry = gather_ignore_directives(parsed);
 
 	// Run each autofixer separately to avoid interrupting logic flow
 	for (const autofixer of Object.values(autofixers)) {
 		walk(
 			parsed.ast as unknown as Node,
-			{ output: content, parsed, desired_svelte_version, async },
+			{ output: content, parsed, desired_svelte_version, async, ignore_registry },
 			autofixer,
 		);
 	}
+
+	// Surface any `svelte-mcp-ignore` directive that listed a
+	// code which never matched — same shape as ESLint's
+	// `no-unused-svelte-ignore` rule. Diagnoses both stale
+	// comments left over from a refactor and typos in the
+	// code name itself.
+	report_unused_directives(content, ignore_registry);
 }