{"owner":"rust-lang","repo":"rustfmt","hasSkills":true,"totalSkillsCount":23,"totalTokensCount":8556,"categories":["project-spec","root-instruction","cursor-rule","windsurf-rule","cline-rule","roo-rule","mcp-config","marketplace","plugin-manifest","copilot-instructions"],"hasMcp":true,"mcpConfig":{"mcpServers":{"rustfmt":{"command":"npx","args":["-y","@modelcontextprotocol/server-rustfmt"]}}},"found":["Design.md","INSTRUCTIONS.md","RULES.md","PROMPT.md","PROMPTS.md","SYSTEM.md","ROUTING.md","SKILLS.md",".cursorrules",".windsurfrules",".clinerules",".roorules",".aideprules",".roomodes","llms.txt","llms-full.txt","mcp.json","marketplace.json","plugin.json",".github/copilot-instructions.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json"],"skills":{"Design.md":"# Some thoughts on the design of rustfmt\n\n## Use cases\n\nA formatting tool can be used in different ways and the different use cases can\naffect the design of the tool. The use cases I'm particularly concerned with are:\n\n* running on a whole repo before check-in\n  - in particular, to replace the `make tidy` pass on the Rust distro\n* running on code from another project that you are adding to your own\n* using for mass changes in code style over a project\n\nSome valid use cases for a formatting tool which I am explicitly not trying to\naddress (although it would be nice, if possible):\n\n* running 'as you type' in an IDE\n* running on arbitrary snippets of code\n* running on Rust-like code, specifically code which doesn't parse\n* use as a pretty printer inside the compiler\n* refactoring\n* formatting totally unformatted source code\n\n\n## Scope and vision\n\nI do not subscribe to the notion that a formatting tool should only change\nwhitespace. I believe that we should semantics preserving, but not necessarily\nsyntax preserving, i.e., we can change the AST of a program.\n\nI.e., we might change glob imports to list or single imports, re-order imports,\nmove bounds to where clauses, combine multiple impls into a single impl, etc.\n\nHowever, we will not change the names of variables or make any changes which\n*could* change the semantics. To be ever so slightly formal, we might imagine\na compilers high level intermediate representation, we should strive to only\nmake changes which do not change the HIR, even if they do change the AST.\n\nI would like to be able to output refactoring scripts for making deeper changes\nthough. (E.g., renaming variables to satisfy our style guidelines).\n\nMy long term goal is that all style lints can be moved from the compiler to\nrustfmt and, as well as warning, can either fix problems or emit refactoring\nscripts to do so.\n\n### Configurability\n\nI believe reformatting should be configurable to some extent. We should read in\noptions from a configuration file and reformat accordingly. We should supply at\nleast a config file which matches the Rust style guidelines.\n\nThere should be multiple modes for running the tool. As well as simply replacing\neach file, we should be able to show the user a list of the changes we would\nmake, or show a list of violations without corrections (the difference being\nthat there are multiple ways to satisfy a given set of style guidelines, and we\nshould distinguish violations from deviations from our own model).\n\n\n## Implementation philosophy\n\nSome details of the philosophy behind the implementation.\n\n\n### Operate on the AST\n\nA reformatting tool can be based on either the AST or a token stream (in Rust\nthis is actually a stream of token trees, but it's not a fundamental difference).\nThere are pros and cons to the two approaches. I have chosen to use the AST\napproach. The primary reasons are that it allows us to do more sophisticated\nmanipulations, rather than just change whitespace, and it gives us more context\nwhen making those changes.\n\nThe advantage of the tokens approach is that you can operate on non-parsable\ncode. I don't care too much about that, it would be nice, but I think being able\nto perform sophisticated transformations is more important. In the future, I hope to\n(optionally) be able to use type information for informing reformatting too. One\nspecific case of unparsable code is macros. Using tokens is certainly easier\nhere, but I believe it is perfectly solvable with the AST approach. At the limit,\nwe can operate on just tokens in the macro case.\n\nI believe that there is not in fact that much difference between the two\napproaches. Due to imperfect span information, under the AST approach, we\nsometimes are reduced to examining tokens or do some re-lexing of our own. Under\nthe tokens approach, you need to implement your own (much simpler) parser. I\nbelieve that as the tool gets more sophisticated, you end up doing more at the\ntoken-level, or having an increasingly sophisticated parser, until at the limit\nyou have the same tool.\n\nHowever, I believe starting from the AST gets you more quickly to a usable and\nuseful tool.\n\n\n### Heuristic rather than algorithmic\n\nMany formatting tools use a very general algorithmic or even algebraic tool for\npretty printing. This results in very elegant code, but I believe does not give\nthe best results. I prefer a more ad hoc approach where each expression/item is\nformatted using custom rules. We hopefully don't end up with too much code due\nto good old fashioned abstraction and code sharing. This will give a bigger code\nbase, but hopefully a better result.\n\nIt also means that there will be some cases we can't format and we have to give\nup. I think that is OK. Hopefully, they are rare enough that manually fixing them\nis not painful. Better to have a tool that gives great code in 99% of cases and\nfails in 1% than a tool which gives 50% great code and 50% ugly code, but never\nfails.\n\n\n### Incremental development\n\nI want rustfmt to be useful as soon as possible and to always be useful. I\nspecifically don't want to have to wait for a feature (or worse, the whole tool)\nto be perfect before it is useful. The main ways this is achieved is to output\nthe source code where we can't yet reformat, be able to turn off new features\nuntil they are ready, and the 'do no harm' principle (see next section).\n\n\n### First, do no harm\n\nUntil rustfmt is perfect, there will always be a trade-off between doing more and\ndoing existing things well. I want to err on the side of the latter.\nSpecifically, rustfmt should never take OK code and make it look worse. If we\ncan't make it better, we should leave it as is. That might mean being less\naggressive than we like or using configurability.\n\n\n### Use the source code as guidance\n\nThere are often multiple ways to format code and satisfy standards. Where this\nis the case, we should use the source code as a hint for reformatting.\nFurthermore, where the code has been formatted in a particular way that satisfies\nthe coding standard, it should not be changed (this is sometimes not possible or\nnot worthwhile due to uniformity being desirable, but it is a useful goal).\n\n\n### Architecture details\n\nWe use the AST from [syntex_syntax], an export of rustc's libsyntax. We use\nsyntex_syntax's visit module to walk the AST to find starting points for\nreformatting. Eventually, we should reformat everything and we shouldn't need\nthe visit module. We keep track of the last formatted position in the code, and\nwhen we reformat the next piece of code we make sure to output the span for all\nthe code in between (handled by missed_spans.rs).\n\n[syntex_syntax]: https://crates.io/crates/syntex_syntax\n\nWe read in formatting configuration from a `rustfmt.toml` file if there is one.\nThe options and their defaults are defined in `config.rs`. A `Config` object is\npassed throughout the formatting code, and each formatting routine looks there\nfor its configuration.\n\nOur visitor keeps track of the desired current indent due to blocks (\n`block_indent`). Each `visit_*` method reformats code according to this indent,\n`config.comment_width()` and `config.max_width()`. Most reformatting that is done\nin the `visit_*` methods is a bit hacky and is meant to be temporary until it can\nbe done properly.\n\nThere are a bunch of methods called `rewrite_*`. They do the bulk of the\nreformatting. These take the AST node to be reformatted (this may not literally\nbe an AST node from syntex_syntax: there might be multiple parameters\ndescribing a logical node), the current indent, and the current width budget.\nThey return a `String` (or sometimes an `Option<String>`) which formats the\ncode in the box given by the indent and width budget. If the method fails, it\nreturns `None` and the calling method then has to fallback in some way to give\nthe callee more space.\n\nSo, in summary, to format a node, we calculate the width budget and then walk down\nthe tree from the node. At a leaf, we generate an actual string and then unwind,\ncombining these strings as we go back up the tree.\n\nFor example, consider a method definition:\n\n```\n    fn foo(a: A, b: B) {\n        ...\n    }\n```\n\nWe start at indent 4, the rewrite function for the whole function knows it must\nwrite `fn foo(` before the arguments and `) {` after them, assuming the max width\nis 100, it thus asks the rewrite argument list function to rewrite with an indent\nof 11 and in a width of 86. Assuming that is possible (obviously in this case),\nit returns a string for the arguments and it can make a string for the function\nheader. If the arguments couldn't be fitted in that space, we might try to\nfallback to a hanging indent, so we try again with indent 8 and width 89.\n","INSTRUCTIONS.md":"# Project Instructions & Agent Workflow\n\nPath: `INSTRUCTIONS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/INSTRUCTIONS.md)","RULES.md":"# Development & Architecture Rules\n\nPath: `RULES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/RULES.md)","PROMPT.md":"# Core System Prompt & Persona\n\nPath: `PROMPT.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/PROMPT.md)","PROMPTS.md":"# Agent Prompts Catalog\n\nPath: `PROMPTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/PROMPTS.md)","SYSTEM.md":"# System Architecture & Agent Directives\n\nPath: `SYSTEM.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/SYSTEM.md)","ROUTING.md":"# Multi-Agent Routing & Delegation Matrix\n\nPath: `ROUTING.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/ROUTING.md)","SKILLS.md":"# Workspace Skills & Capabilities Index\n\nPath: `SKILLS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/SKILLS.md)",".cursorrules":"# Cursor IDE Native Rules\n\nPath: `.cursorrules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.cursorrules)",".windsurfrules":"# Windsurf Cascade Agent Rules\n\nPath: `.windsurfrules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.windsurfrules)",".clinerules":"# Cline Extension Native Directives\n\nPath: `.clinerules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.clinerules)",".roorules":"# Roo Code Autonomous Agent Rules\n\nPath: `.roorules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.roorules)",".aideprules":"# Aider Coding Assistant Guidelines\n\nPath: `.aideprules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.aideprules)",".roomodes":"# Roo Code Custom Persona Modes\n\nPath: `.roomodes`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.roomodes)","llms.txt":"# LLM Index & Context Digest\n\nPath: `llms.txt`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/llms.txt)","llms-full.txt":"# LLM Full Documentation Context\n\nPath: `llms-full.txt`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/llms-full.txt)","mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/mcp.json)","marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/marketplace.json)","plugin.json":"# Plugin Plugin Manifest\n\nPath: `plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/plugin.json)",".github/copilot-instructions.md":"# GitHub Copilot Instructions\n\nPath: `.github/copilot-instructions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.github/copilot-instructions.md)",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.claude-plugin/plugin.json)"},"files":{"Design.md":"# Some thoughts on the design of rustfmt\n\n## Use cases\n\nA formatting tool can be used in different ways and the different use cases can\naffect the design of the tool. The use cases I'm particularly concerned with are:\n\n* running on a whole repo before check-in\n  - in particular, to replace the `make tidy` pass on the Rust distro\n* running on code from another project that you are adding to your own\n* using for mass changes in code style over a project\n\nSome valid use cases for a formatting tool which I am explicitly not trying to\naddress (although it would be nice, if possible):\n\n* running 'as you type' in an IDE\n* running on arbitrary snippets of code\n* running on Rust-like code, specifically code which doesn't parse\n* use as a pretty printer inside the compiler\n* refactoring\n* formatting totally unformatted source code\n\n\n## Scope and vision\n\nI do not subscribe to the notion that a formatting tool should only change\nwhitespace. I believe that we should semantics preserving, but not necessarily\nsyntax preserving, i.e., we can change the AST of a program.\n\nI.e., we might change glob imports to list or single imports, re-order imports,\nmove bounds to where clauses, combine multiple impls into a single impl, etc.\n\nHowever, we will not change the names of variables or make any changes which\n*could* change the semantics. To be ever so slightly formal, we might imagine\na compilers high level intermediate representation, we should strive to only\nmake changes which do not change the HIR, even if they do change the AST.\n\nI would like to be able to output refactoring scripts for making deeper changes\nthough. (E.g., renaming variables to satisfy our style guidelines).\n\nMy long term goal is that all style lints can be moved from the compiler to\nrustfmt and, as well as warning, can either fix problems or emit refactoring\nscripts to do so.\n\n### Configurability\n\nI believe reformatting should be configurable to some extent. We should read in\noptions from a configuration file and reformat accordingly. We should supply at\nleast a config file which matches the Rust style guidelines.\n\nThere should be multiple modes for running the tool. As well as simply replacing\neach file, we should be able to show the user a list of the changes we would\nmake, or show a list of violations without corrections (the difference being\nthat there are multiple ways to satisfy a given set of style guidelines, and we\nshould distinguish violations from deviations from our own model).\n\n\n## Implementation philosophy\n\nSome details of the philosophy behind the implementation.\n\n\n### Operate on the AST\n\nA reformatting tool can be based on either the AST or a token stream (in Rust\nthis is actually a stream of token trees, but it's not a fundamental difference).\nThere are pros and cons to the two approaches. I have chosen to use the AST\napproach. The primary reasons are that it allows us to do more sophisticated\nmanipulations, rather than just change whitespace, and it gives us more context\nwhen making those changes.\n\nThe advantage of the tokens approach is that you can operate on non-parsable\ncode. I don't care too much about that, it would be nice, but I think being able\nto perform sophisticated transformations is more important. In the future, I hope to\n(optionally) be able to use type information for informing reformatting too. One\nspecific case of unparsable code is macros. Using tokens is certainly easier\nhere, but I believe it is perfectly solvable with the AST approach. At the limit,\nwe can operate on just tokens in the macro case.\n\nI believe that there is not in fact that much difference between the two\napproaches. Due to imperfect span information, under the AST approach, we\nsometimes are reduced to examining tokens or do some re-lexing of our own. Under\nthe tokens approach, you need to implement your own (much simpler) parser. I\nbelieve that as the tool gets more sophisticated, you end up doing more at the\ntoken-level, or having an increasingly sophisticated parser, until at the limit\nyou have the same tool.\n\nHowever, I believe starting from the AST gets you more quickly to a usable and\nuseful tool.\n\n\n### Heuristic rather than algorithmic\n\nMany formatting tools use a very general algorithmic or even algebraic tool for\npretty printing. This results in very elegant code, but I believe does not give\nthe best results. I prefer a more ad hoc approach where each expression/item is\nformatted using custom rules. We hopefully don't end up with too much code due\nto good old fashioned abstraction and code sharing. This will give a bigger code\nbase, but hopefully a better result.\n\nIt also means that there will be some cases we can't format and we have to give\nup. I think that is OK. Hopefully, they are rare enough that manually fixing them\nis not painful. Better to have a tool that gives great code in 99% of cases and\nfails in 1% than a tool which gives 50% great code and 50% ugly code, but never\nfails.\n\n\n### Incremental development\n\nI want rustfmt to be useful as soon as possible and to always be useful. I\nspecifically don't want to have to wait for a feature (or worse, the whole tool)\nto be perfect before it is useful. The main ways this is achieved is to output\nthe source code where we can't yet reformat, be able to turn off new features\nuntil they are ready, and the 'do no harm' principle (see next section).\n\n\n### First, do no harm\n\nUntil rustfmt is perfect, there will always be a trade-off between doing more and\ndoing existing things well. I want to err on the side of the latter.\nSpecifically, rustfmt should never take OK code and make it look worse. If we\ncan't make it better, we should leave it as is. That might mean being less\naggressive than we like or using configurability.\n\n\n### Use the source code as guidance\n\nThere are often multiple ways to format code and satisfy standards. Where this\nis the case, we should use the source code as a hint for reformatting.\nFurthermore, where the code has been formatted in a particular way that satisfies\nthe coding standard, it should not be changed (this is sometimes not possible or\nnot worthwhile due to uniformity being desirable, but it is a useful goal).\n\n\n### Architecture details\n\nWe use the AST from [syntex_syntax], an export of rustc's libsyntax. We use\nsyntex_syntax's visit module to walk the AST to find starting points for\nreformatting. Eventually, we should reformat everything and we shouldn't need\nthe visit module. We keep track of the last formatted position in the code, and\nwhen we reformat the next piece of code we make sure to output the span for all\nthe code in between (handled by missed_spans.rs).\n\n[syntex_syntax]: https://crates.io/crates/syntex_syntax\n\nWe read in formatting configuration from a `rustfmt.toml` file if there is one.\nThe options and their defaults are defined in `config.rs`. A `Config` object is\npassed throughout the formatting code, and each formatting routine looks there\nfor its configuration.\n\nOur visitor keeps track of the desired current indent due to blocks (\n`block_indent`). Each `visit_*` method reformats code according to this indent,\n`config.comment_width()` and `config.max_width()`. Most reformatting that is done\nin the `visit_*` methods is a bit hacky and is meant to be temporary until it can\nbe done properly.\n\nThere are a bunch of methods called `rewrite_*`. They do the bulk of the\nreformatting. These take the AST node to be reformatted (this may not literally\nbe an AST node from syntex_syntax: there might be multiple parameters\ndescribing a logical node), the current indent, and the current width budget.\nThey return a `String` (or sometimes an `Option<String>`) which formats the\ncode in the box given by the indent and width budget. If the method fails, it\nreturns `None` and the calling method then has to fallback in some way to give\nthe callee more space.\n\nSo, in summary, to format a node, we calculate the width budget and then walk down\nthe tree from the node. At a leaf, we generate an actual string and then unwind,\ncombining these strings as we go back up the tree.\n\nFor example, consider a method definition:\n\n```\n    fn foo(a: A, b: B) {\n        ...\n    }\n```\n\nWe start at indent 4, the rewrite function for the whole function knows it must\nwrite `fn foo(` before the arguments and `) {` after them, assuming the max width\nis 100, it thus asks the rewrite argument list function to rewrite with an indent\nof 11 and in a width of 86. Assuming that is possible (obviously in this case),\nit returns a string for the arguments and it can make a string for the function\nheader. If the arguments couldn't be fitted in that space, we might try to\nfallback to a hanging indent, so we try again with indent 8 and width 89.\n","INSTRUCTIONS.md":"# Project Instructions & Agent Workflow\n\nPath: `INSTRUCTIONS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/INSTRUCTIONS.md)","RULES.md":"# Development & Architecture Rules\n\nPath: `RULES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/RULES.md)","PROMPT.md":"# Core System Prompt & Persona\n\nPath: `PROMPT.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/PROMPT.md)","PROMPTS.md":"# Agent Prompts Catalog\n\nPath: `PROMPTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/PROMPTS.md)","SYSTEM.md":"# System Architecture & Agent Directives\n\nPath: `SYSTEM.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/SYSTEM.md)","ROUTING.md":"# Multi-Agent Routing & Delegation Matrix\n\nPath: `ROUTING.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/ROUTING.md)","SKILLS.md":"# Workspace Skills & Capabilities Index\n\nPath: `SKILLS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/SKILLS.md)",".cursorrules":"# Cursor IDE Native Rules\n\nPath: `.cursorrules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.cursorrules)",".windsurfrules":"# Windsurf Cascade Agent Rules\n\nPath: `.windsurfrules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.windsurfrules)",".clinerules":"# Cline Extension Native Directives\n\nPath: `.clinerules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.clinerules)",".roorules":"# Roo Code Autonomous Agent Rules\n\nPath: `.roorules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.roorules)",".aideprules":"# Aider Coding Assistant Guidelines\n\nPath: `.aideprules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.aideprules)",".roomodes":"# Roo Code Custom Persona Modes\n\nPath: `.roomodes`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.roomodes)","llms.txt":"# LLM Index & Context Digest\n\nPath: `llms.txt`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/llms.txt)","llms-full.txt":"# LLM Full Documentation Context\n\nPath: `llms-full.txt`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/llms-full.txt)","mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/mcp.json)","marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/marketplace.json)","plugin.json":"# Plugin Plugin Manifest\n\nPath: `plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/plugin.json)",".github/copilot-instructions.md":"# GitHub Copilot Instructions\n\nPath: `.github/copilot-instructions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.github/copilot-instructions.md)",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.claude-plugin/plugin.json)"},"items":[{"name":".aideprules","path":".aideprules","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.aideprules","title":"Aider Coding Assistant Guidelines","category":"root-instruction","format":"markdown","content":"# Aider Coding Assistant Guidelines\n\nPath: `.aideprules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.aideprules)","tokens":300,"sizeBytes":156},{"name":"INSTRUCTIONS.md","path":"INSTRUCTIONS.md","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/INSTRUCTIONS.md","title":"Project Instructions & Agent Workflow","category":"root-instruction","format":"markdown","content":"# Project Instructions & Agent Workflow\n\nPath: `INSTRUCTIONS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/INSTRUCTIONS.md)","tokens":300,"sizeBytes":168},{"name":"llms-full.txt","path":"llms-full.txt","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/llms-full.txt","title":"LLM Full Documentation Context","category":"root-instruction","format":"text","content":"# LLM Full Documentation Context\n\nPath: `llms-full.txt`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/llms-full.txt)","tokens":300,"sizeBytes":157},{"name":"llms.txt","path":"llms.txt","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/llms.txt","title":"LLM Index & Context Digest","category":"root-instruction","format":"text","content":"# LLM Index & Context Digest\n\nPath: `llms.txt`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/llms.txt)","tokens":300,"sizeBytes":143},{"name":"PROMPT.md","path":"PROMPT.md","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/PROMPT.md","title":"Core System Prompt & Persona","category":"root-instruction","format":"markdown","content":"# Core System Prompt & Persona\n\nPath: `PROMPT.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/PROMPT.md)","tokens":300,"sizeBytes":147},{"name":"PROMPTS.md","path":"PROMPTS.md","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/PROMPTS.md","title":"Agent Prompts Catalog","category":"root-instruction","format":"markdown","content":"# Agent Prompts Catalog\n\nPath: `PROMPTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/PROMPTS.md)","tokens":300,"sizeBytes":142},{"name":"ROUTING.md","path":"ROUTING.md","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/ROUTING.md","title":"Multi-Agent Routing & Delegation Matrix","category":"root-instruction","format":"markdown","content":"# Multi-Agent Routing & Delegation Matrix\n\nPath: `ROUTING.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/ROUTING.md)","tokens":300,"sizeBytes":160},{"name":"RULES.md","path":"RULES.md","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/RULES.md","title":"Development & Architecture Rules","category":"root-instruction","format":"markdown","content":"# Development & Architecture Rules\n\nPath: `RULES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/RULES.md)","tokens":300,"sizeBytes":149},{"name":"SKILLS.md","path":"SKILLS.md","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/SKILLS.md","title":"Workspace Skills & Capabilities Index","category":"root-instruction","format":"markdown","content":"# Workspace Skills & Capabilities Index\n\nPath: `SKILLS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/SKILLS.md)","tokens":300,"sizeBytes":156},{"name":"SYSTEM.md","path":"SYSTEM.md","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/SYSTEM.md","title":"System Architecture & Agent Directives","category":"root-instruction","format":"markdown","content":"# System Architecture & Agent Directives\n\nPath: `SYSTEM.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/SYSTEM.md)","tokens":300,"sizeBytes":157},{"name":"Design.md","path":"Design.md","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/Design.md","title":"UI Design System & Style Tokens","category":"project-spec","format":"markdown","content":"# Some thoughts on the design of rustfmt\n\n## Use cases\n\nA formatting tool can be used in different ways and the different use cases can\naffect the design of the tool. The use cases I'm particularly concerned with are:\n\n* running on a whole repo before check-in\n  - in particular, to replace the `make tidy` pass on the Rust distro\n* running on code from another project that you are adding to your own\n* using for mass changes in code style over a project\n\nSome valid use cases for a formatting tool which I am explicitly not trying to\naddress (although it would be nice, if possible):\n\n* running 'as you type' in an IDE\n* running on arbitrary snippets of code\n* running on Rust-like code, specifically code which doesn't parse\n* use as a pretty printer inside the compiler\n* refactoring\n* formatting totally unformatted source code\n\n\n## Scope and vision\n\nI do not subscribe to the notion that a formatting tool should only change\nwhitespace. I believe that we should semantics preserving, but not necessarily\nsyntax preserving, i.e., we can change the AST of a program.\n\nI.e., we might change glob imports to list or single imports, re-order imports,\nmove bounds to where clauses, combine multiple impls into a single impl, etc.\n\nHowever, we will not change the names of variables or make any changes which\n*could* change the semantics. To be ever so slightly formal, we might imagine\na compilers high level intermediate representation, we should strive to only\nmake changes which do not change the HIR, even if they do change the AST.\n\nI would like to be able to output refactoring scripts for making deeper changes\nthough. (E.g., renaming variables to satisfy our style guidelines).\n\nMy long term goal is that all style lints can be moved from the compiler to\nrustfmt and, as well as warning, can either fix problems or emit refactoring\nscripts to do so.\n\n### Configurability\n\nI believe reformatting should be configurable to some extent. We should read in\noptions from a configuration file and reformat accordingly. We should supply at\nleast a config file which matches the Rust style guidelines.\n\nThere should be multiple modes for running the tool. As well as simply replacing\neach file, we should be able to show the user a list of the changes we would\nmake, or show a list of violations without corrections (the difference being\nthat there are multiple ways to satisfy a given set of style guidelines, and we\nshould distinguish violations from deviations from our own model).\n\n\n## Implementation philosophy\n\nSome details of the philosophy behind the implementation.\n\n\n### Operate on the AST\n\nA reformatting tool can be based on either the AST or a token stream (in Rust\nthis is actually a stream of token trees, but it's not a fundamental difference).\nThere are pros and cons to the two approaches. I have chosen to use the AST\napproach. The primary reasons are that it allows us to do more sophisticated\nmanipulations, rather than just change whitespace, and it gives us more context\nwhen making those changes.\n\nThe advantage of the tokens approach is that you can operate on non-parsable\ncode. I don't care too much about that, it would be nice, but I think being able\nto perform sophisticated transformations is more important. In the future, I hope to\n(optionally) be able to use type information for informing reformatting too. One\nspecific case of unparsable code is macros. Using tokens is certainly easier\nhere, but I believe it is perfectly solvable with the AST approach. At the limit,\nwe can operate on just tokens in the macro case.\n\nI believe that there is not in fact that much difference between the two\napproaches. Due to imperfect span information, under the AST approach, we\nsometimes are reduced to examining tokens or do some re-lexing of our own. Under\nthe tokens approach, you need to implement your own (much simpler) parser. I\nbelieve that as the tool gets more sophisticated, you end up doing more at the\ntoken-level, or having an increasingly sophisticated parser, until at the limit\nyou have the same tool.\n\nHowever, I believe starting from the AST gets you more quickly to a usable and\nuseful tool.\n\n\n### Heuristic rather than algorithmic\n\nMany formatting tools use a very general algorithmic or even algebraic tool for\npretty printing. This results in very elegant code, but I believe does not give\nthe best results. I prefer a more ad hoc approach where each expression/item is\nformatted using custom rules. We hopefully don't end up with too much code due\nto good old fashioned abstraction and code sharing. This will give a bigger code\nbase, but hopefully a better result.\n\nIt also means that there will be some cases we can't format and we have to give\nup. I think that is OK. Hopefully, they are rare enough that manually fixing them\nis not painful. Better to have a tool that gives great code in 99% of cases and\nfails in 1% than a tool which gives 50% great code and 50% ugly code, but never\nfails.\n\n\n### Incremental development\n\nI want rustfmt to be useful as soon as possible and to always be useful. I\nspecifically don't want to have to wait for a feature (or worse, the whole tool)\nto be perfect before it is useful. The main ways this is achieved is to output\nthe source code where we can't yet reformat, be able to turn off new features\nuntil they are ready, and the 'do no harm' principle (see next section).\n\n\n### First, do no harm\n\nUntil rustfmt is perfect, there will always be a trade-off between doing more and\ndoing existing things well. I want to err on the side of the latter.\nSpecifically, rustfmt should never take OK code and make it look worse. If we\ncan't make it better, we should leave it as is. That might mean being less\naggressive than we like or using configurability.\n\n\n### Use the source code as guidance\n\nThere are often multiple ways to format code and satisfy standards. Where this\nis the case, we should use the source code as a hint for reformatting.\nFurthermore, where the code has been formatted in a particular way that satisfies\nthe coding standard, it should not be changed (this is sometimes not possible or\nnot worthwhile due to uniformity being desirable, but it is a useful goal).\n\n\n### Architecture details\n\nWe use the AST from [syntex_syntax], an export of rustc's libsyntax. We use\nsyntex_syntax's visit module to walk the AST to find starting points for\nreformatting. Eventually, we should reformat everything and we shouldn't need\nthe visit module. We keep track of the last formatted position in the code, and\nwhen we reformat the next piece of code we make sure to output the span for all\nthe code in between (handled by missed_spans.rs).\n\n[syntex_syntax]: https://crates.io/crates/syntex_syntax\n\nWe read in formatting configuration from a `rustfmt.toml` file if there is one.\nThe options and their defaults are defined in `config.rs`. A `Config` object is\npassed throughout the formatting code, and each formatting routine looks there\nfor its configuration.\n\nOur visitor keeps track of the desired current indent due to blocks (\n`block_indent`). Each `visit_*` method reformats code according to this indent,\n`config.comment_width()` and `config.max_width()`. Most reformatting that is done\nin the `visit_*` methods is a bit hacky and is meant to be temporary until it can\nbe done properly.\n\nThere are a bunch of methods called `rewrite_*`. They do the bulk of the\nreformatting. These take the AST node to be reformatted (this may not literally\nbe an AST node from syntex_syntax: there might be multiple parameters\ndescribing a logical node), the current indent, and the current width budget.\nThey return a `String` (or sometimes an `Option<String>`) which formats the\ncode in the box given by the indent and width budget. If the method fails, it\nreturns `None` and the calling method then has to fallback in some way to give\nthe callee more space.\n\nSo, in summary, to format a node, we calculate the width budget and then walk down\nthe tree from the node. At a leaf, we generate an actual string and then unwind,\ncombining these strings as we go back up the tree.\n\nFor example, consider a method definition:\n\n```\n    fn foo(a: A, b: B) {\n        ...\n    }\n```\n\nWe start at indent 4, the rewrite function for the whole function knows it must\nwrite `fn foo(` before the arguments and `) {` after them, assuming the max width\nis 100, it thus asks the rewrite argument list function to rewrite with an indent\nof 11 and in a width of 86. Assuming that is possible (obviously in this case),\nit returns a string for the arguments and it can make a string for the function\nheader. If the arguments couldn't be fitted in that space, we might try to\nfallback to a hanging indent, so we try again with indent 8 and width 89.\n","isInternal":false,"tokens":1956,"sizeBytes":8709},{"name":".cursorrules","path":".cursorrules","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.cursorrules","title":"Cursor IDE Native Rules","category":"cursor-rule","format":"markdown","content":"# Cursor IDE Native Rules\n\nPath: `.cursorrules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.cursorrules)","tokens":300,"sizeBytes":148},{"name":".windsurfrules","path":".windsurfrules","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.windsurfrules","title":"Windsurf Cascade Agent Rules","category":"windsurf-rule","format":"markdown","content":"# Windsurf Cascade Agent Rules\n\nPath: `.windsurfrules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.windsurfrules)","tokens":300,"sizeBytes":157},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# GitHub Copilot Instructions\n\nPath: `.github/copilot-instructions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.github/copilot-instructions.md)","tokens":300,"sizeBytes":190},{"name":".roomodes","path":".roomodes","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.roomodes","title":"Roo Code Custom Persona Modes","category":"roo-rule","format":"markdown","content":"# Roo Code Custom Persona Modes\n\nPath: `.roomodes`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.roomodes)","tokens":300,"sizeBytes":148},{"name":".roorules","path":".roorules","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.roorules","title":"Roo Code Autonomous Agent Rules","category":"roo-rule","format":"markdown","content":"# Roo Code Autonomous Agent Rules\n\nPath: `.roorules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.roorules)","tokens":300,"sizeBytes":150},{"name":".clinerules","path":".clinerules","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.clinerules","title":"Cline Extension Native Directives","category":"cline-rule","format":"markdown","content":"# Cline Extension Native Directives\n\nPath: `.clinerules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.clinerules)","tokens":300,"sizeBytes":156},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":196},{"name":"marketplace.json","path":"marketplace.json","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/marketplace.json)","tokens":300,"sizeBytes":166},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":182},{"name":"plugin.json","path":"plugin.json","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/plugin.json","title":"Plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# Plugin Plugin Manifest\n\nPath: `plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/plugin.json)","tokens":300,"sizeBytes":145},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":175},{"name":"mcp.json","path":"mcp.json","rawUrl":"https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/mcp.json)","tokens":300,"sizeBytes":159}],"systemPromptSnippet":"<yakaai_skills repo=\"rust-lang/rustfmt\">\n<!-- File: .aideprules (Tokens: ~300 | Category: root-instruction) -->\n# Aider Coding Assistant Guidelines\n\nPath: `.aideprules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.aideprules)\n\n<!-- File: INSTRUCTIONS.md (Tokens: ~300 | Category: root-instruction) -->\n# Project Instructions & Agent Workflow\n\nPath: `INSTRUCTIONS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/INSTRUCTIONS.md)\n\n<!-- File: llms-full.txt (Tokens: ~300 | Category: root-instruction) -->\n# LLM Full Documentation Context\n\nPath: `llms-full.txt`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/llms-full.txt)\n\n<!-- File: llms.txt (Tokens: ~300 | Category: root-instruction) -->\n# LLM Index & Context Digest\n\nPath: `llms.txt`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/llms.txt)\n\n<!-- File: PROMPT.md (Tokens: ~300 | Category: root-instruction) -->\n# Core System Prompt & Persona\n\nPath: `PROMPT.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/PROMPT.md)\n\n<!-- File: PROMPTS.md (Tokens: ~300 | Category: root-instruction) -->\n# Agent Prompts Catalog\n\nPath: `PROMPTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/PROMPTS.md)\n\n<!-- File: ROUTING.md (Tokens: ~300 | Category: root-instruction) -->\n# Multi-Agent Routing & Delegation Matrix\n\nPath: `ROUTING.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/ROUTING.md)\n\n<!-- File: RULES.md (Tokens: ~300 | Category: root-instruction) -->\n# Development & Architecture Rules\n\nPath: `RULES.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/RULES.md)\n\n<!-- File: SKILLS.md (Tokens: ~300 | Category: root-instruction) -->\n# Workspace Skills & Capabilities Index\n\nPath: `SKILLS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/SKILLS.md)\n\n<!-- File: SYSTEM.md (Tokens: ~300 | Category: root-instruction) -->\n# System Architecture & Agent Directives\n\nPath: `SYSTEM.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/SYSTEM.md)\n\n<!-- File: Design.md (Tokens: ~1956 | Category: project-spec) -->\n# Some thoughts on the design of rustfmt\n\n## Use cases\n\nA formatting tool can be used in different ways and the different use cases can\naffect the design of the tool. The use cases I'm particularly concerned with are:\n\n* running on a whole repo before check-in\n  - in particular, to replace the `make tidy` pass on the Rust distro\n* running on code from another project that you are adding to your own\n* using for mass changes in code style over a project\n\nSome valid use cases for a formatting tool which I am explicitly not trying to\naddress (although it would be nice, if possible):\n\n* running 'as you type' in an IDE\n* running on arbitrary snippets of code\n* running on Rust-like code, specifically code which doesn't parse\n* use as a pretty printer inside the compiler\n* refactoring\n* formatting totally unformatted source code\n\n\n## Scope and vision\n\nI do not subscribe to the notion that a formatting tool should only change\nwhitespace. I believe that we should semantics preserving, but not necessarily\nsyntax preserving, i.e., we can change the AST of a program.\n\nI.e., we might change glob imports to list or single imports, re-order imports,\nmove bounds to where clauses, combine multiple impls into a single impl, etc.\n\nHowever, we will not change the names of variables or make any changes which\n*could* change the semantics. To be ever so slightly formal, we might imagine\na compilers high level intermediate representation, we should strive to only\nmake changes which do not change the HIR, even if they do change the AST.\n\nI would like to be able to output refactoring scripts for making deeper changes\nthough. (E.g., renaming variables to satisfy our style guidelines).\n\nMy long term goal is that all style lints can be moved from the compiler to\nrustfmt and, as well as warning, can either fix problems or emit refactoring\nscripts to do so.\n\n### Configurability\n\nI believe reformatting should be configurable to some extent. We should read in\noptions from a configuration file and reformat accordingly. We should supply at\nleast a config file which matches the Rust style guidelines.\n\nThere should be multiple modes for running the tool. As well as simply replacing\neach file, we should be able to show the user a list of the changes we would\nmake, or show a list of violations without corrections (the difference being\nthat there are multiple ways to satisfy a given set of style guidelines, and we\nshould distinguish violations from deviations from our own model).\n\n\n## Implementation philosophy\n\nSome details of the philosophy behind the implementation.\n\n\n### Operate on the AST\n\nA reformatting tool can be based on either the AST or a token stream (in Rust\nthis is actually a stream of token trees, but it's not a fundamental difference).\nThere are pros and cons to the two approaches. I have chosen to use the AST\napproach. The primary reasons are that it allows us to do more sophisticated\nmanipulations, rather than just change whitespace, and it gives us more context\nwhen making those changes.\n\nThe advantage of the tokens approach is that you can operate on non-parsable\ncode. I don't care too much about that, it would be nice, but I think being able\nto perform sophisticated transformations is more important. In the future, I hope to\n(optionally) be able to use type information for informing reformatting too. One\nspecific case of unparsable code is macros. Using tokens is certainly easier\nhere, but I believe it is perfectly solvable with the AST approach. At the limit,\nwe can operate on just tokens in the macro case.\n\nI believe that there is not in fact that much difference between the two\napproaches. Due to imperfect span information, under the AST approach, we\nsometimes are reduced to examining tokens or do some re-lexing of our own. Under\nthe tokens approach, you need to implement your own (much simpler) parser. I\nbelieve that as the tool gets more sophisticated, you end up doing more at the\ntoken-level, or having an increasingly sophisticated parser, until at the limit\nyou have the same tool.\n\nHowever, I believe starting from the AST gets you more quickly to a usable and\nuseful tool.\n\n\n### Heuristic rather than algorithmic\n\nMany formatting tools use a very general algorithmic or even algebraic tool for\npretty printing. This results in very elegant code, but I believe does not give\nthe best results. I prefer a more ad hoc approach where each expression/item is\nformatted using custom rules. We hopefully don't end up with too much code due\nto good old fashioned abstraction and code sharing. This will give a bigger code\nbase, but hopefully a better result.\n\nIt also means that there will be some cases we can't format and we have to give\nup. I think that is OK. Hopefully, they are rare enough that manually fixing them\nis not painful. Better to have a tool that gives great code in 99% of cases and\nfails in 1% than a tool which gives 50% great code and 50% ugly code, but never\nfails.\n\n\n### Incremental development\n\nI want rustfmt to be useful as soon as possible and to always be useful. I\nspecifically don't want to have to wait for a feature (or worse, the whole tool)\nto be perfect before it is useful. The main ways this is achieved is to output\nthe source code where we can't yet reformat, be able to turn off new features\nuntil they are ready, and the 'do no harm' principle (see next section).\n\n\n### First, do no harm\n\nUntil rustfmt is perfect, there will always be a trade-off between doing more and\ndoing existing things well. I want to err on the side of the latter.\nSpecifically, rustfmt should never take OK code and make it look worse. If we\ncan't make it better, we should leave it as is. That might mean being less\naggressive than we like or using configurability.\n\n\n### Use the source code as guidance\n\nThere are often multiple ways to format code and satisfy standards. Where this\nis the case, we should use the source code as a hint for reformatting.\nFurthermore, where the code has been formatted in a particular way that satisfies\nthe coding standard, it should not be changed (this is sometimes not possible or\nnot worthwhile due to uniformity being desirable, but it is a useful goal).\n\n\n### Architecture details\n\nWe use the AST from [syntex_syntax], an export of rustc's libsyntax. We use\nsyntex_syntax's visit module to walk the AST to find starting points for\nreformatting. Eventually, we should reformat everything and we shouldn't need\nthe visit module. We keep track of the last formatted position in the code, and\nwhen we reformat the next piece of code we make sure to output the span for all\nthe code in between (handled by missed_spans.rs).\n\n[syntex_syntax]: https://crates.io/crates/syntex_syntax\n\nWe read in formatting configuration from a `rustfmt.toml` file if there is one.\nThe options and their defaults are defined in `config.rs`. A `Config` object is\npassed throughout the formatting code, and each formatting routine looks there\nfor its configuration.\n\nOur visitor keeps track of the desired current indent due to blocks (\n`block_indent`). Each `visit_*` method reformats code according to this indent,\n`config.comment_width()` and `config.max_width()`. Most reformatting that is done\nin the `visit_*` methods is a bit hacky and is meant to be temporary until it can\nbe done properly.\n\nThere are a bunch of methods called `rewrite_*`. They do the bulk of the\nreformatting. These take the AST node to be reformatted (this may not literally\nbe an AST node from syntex_syntax: there might be multiple parameters\ndescribing a logical node), the current indent, and the current width budget.\nThey return a `String` (or sometimes an `Option<String>`) which formats the\ncode in the box given by the indent and width budget. If the method fails, it\nreturns `None` and the calling method then has to fallback in some way to give\nthe callee more space.\n\nSo, in summary, to format a node, we calculate the width budget and then walk down\nthe tree from the node. At a leaf, we generate an actual string and then unwind,\ncombining these strings as we go back up the tree.\n\nFor example, consider a method definition:\n\n```\n    fn foo(a: A, b: B) {\n        ...\n    }\n```\n\nWe start at indent 4, the rewrite function for the whole function knows it must\nwrite `fn foo(` before the arguments and `) {` after them, assuming the max width\nis 100, it thus asks the rewrite argument list function to rewrite with an indent\nof 11 and in a width of 86. Assuming that is possible (obviously in this case),\nit returns a string for the arguments and it can make a string for the function\nheader. If the arguments couldn't be fitted in that space, we might try to\nfallback to a hanging indent, so we try again with indent 8 and width 89.\n\n<!-- File: .cursorrules (Tokens: ~300 | Category: cursor-rule) -->\n# Cursor IDE Native Rules\n\nPath: `.cursorrules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.cursorrules)\n\n<!-- File: .windsurfrules (Tokens: ~300 | Category: windsurf-rule) -->\n# Windsurf Cascade Agent Rules\n\nPath: `.windsurfrules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.windsurfrules)\n\n<!-- File: .github/copilot-instructions.md (Tokens: ~300 | Category: copilot-instructions) -->\n# GitHub Copilot Instructions\n\nPath: `.github/copilot-instructions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.github/copilot-instructions.md)\n\n<!-- File: .roomodes (Tokens: ~300 | Category: roo-rule) -->\n# Roo Code Custom Persona Modes\n\nPath: `.roomodes`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.roomodes)\n\n<!-- File: .roorules (Tokens: ~300 | Category: roo-rule) -->\n# Roo Code Autonomous Agent Rules\n\nPath: `.roorules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.roorules)\n\n<!-- File: .clinerules (Tokens: ~300 | Category: cline-rule) -->\n# Cline Extension Native Directives\n\nPath: `.clinerules`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.clinerules)\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.claude-plugin/marketplace.json)\n\n<!-- File: marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/marketplace.json)\n\n<!-- File: .claude-plugin/plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.claude-plugin/plugin.json)\n\n<!-- File: plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# Plugin Plugin Manifest\n\nPath: `plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/plugin.json)\n\n<!-- File: .cursor/mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/.cursor/mcp.json)\n\n<!-- File: mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/rust-lang/rustfmt/HEAD/mcp.json)\n</yakaai_skills>"}