First impressions report

[aszenz]

First impressions of running Mago

Hello @azjezz , great work on the project, this is a rough dump of my first run experience on a fairly large real world symfony project.

Installation

• Great on boarding experience, easy to install
• Only small feedback is maybe the shell cmd can be directly shown in the readme instead of going to docs first.

Running mago init

• Not clear how to configure separate source directories for fmt/lint/analyze, I normally like to ignore static analysis for tests directories.
• Not clear how to configure includes/excludes for lint/fmt/analyze separately

Running mago fmt -c

• Wow, it really is fast , the progress bar finishes in seconds on this large project.
• Output is INFO Found 3247 file(s) that need formatting.. I would really like to know why these files need formatting, which rules are they breaking, this would help me in configuring the project.

I imagine an output like this

 INFO Found 3247 file(s) that need formatting.

 1000 lines above maximum print width, configure using 

[formatter]
print-width = 120

 2000 lines breaking PSR-12 rules

Running mago lint

• Again, it's really fast.
• When the output is large, maybe use a cli pager like less automatically if it's installed, not sure about this one.
• When reviewing issues, I would like to know to disable them in case i don't find them suitable for the project, I think the output already shows issue-key, so it's just a matter of showing how to enable/disable issue keys, at the top/bottom.
• Not clear how to auto-fix, show which cmd to use for auto-fixing

Running mago analyze

• Again faster than my expectations
• Same feedback as lint, show how to disable each rule
• Lot of errors so I tried to run it on a subset of the code-base

Running mago analyze src/Order

• Seems to not find classes outside of this directory, I expected it to search the whole codebase but only surface issues from src/Order, but it only seems to be scanning this directory.

[azjezz]

Hi! Thank you so much for taking the time to run Mago on a large project and write up such detailed and thoughtful first impressions. This is exactly the kind of feedback that is incredibly valuable for us.

I'd like to address each of your points below.

Installation

Only small feedback is maybe the shell cmd can be directly shown in the readme instead of going to docs first.

That's a great observation. We recently moved the installation methods to the docs because the list of options was getting long, but I completely agree that having the most common/easiest method directly in the README is better for onboarding. I'll add it back.

Configuration (mago init)

Not clear how to configure separate source directories for fmt/lint/analyze, I normally like to ignore static analysis for tests directories.

You're right, our docs/init command need to be clearer on this. The [sources] table in your mago.toml is the key here. It has three main properties:

• paths = ["src", "lib"]: This is your primary codebase, which will be used by all tools (fmt, lint, analyze).
• includes = ["vendor"]: A list of paths to scan for symbols, like third-party dependencies. This is currently used by the analyzer to know where other classes are defined.
• excludes = ["vendor/psalm/psalm", "vendor/phpstan/phpstan"]: A list of paths and patterns to ignore completely. It is highly recommended to add generated code or dev-dependencies here. This not only simplifies things for Mago but can also provide a significant performance boost, as the analyzer has less code to scan.

While you can't override includes on a per-tool basis yet, you can extend the excludes for each tool. This allows you to ignore specific directories for formatting or analysis, like so:

[formatter]
excludes = ["lib/", "generated/"]

[linter]
excludes = ["lib/"]

[analyzer]
excludes = ["tests/"]

Formatter (mago fmt)

Output is INFO Found 3247 file(s) that need formatting.. I would really like to know why these files need formatting, which rules are they breaking, this would help me in configuring the project.

This is an excellent question that gets to the core of how Mago's formatter works.

Unlike tools like php-cs-fixer or phpcs, mago fmt is not a linter that fixes a list of rules. It is a true code formatter, similar to rustfmt or gofmt. It works by:

1. Parsing your code into an Abstract Syntax Tree (AST).
2. Throwing away all of your original formatting.
3. Re-printing the code from the AST using a custom formatter for each type of node.

A file is considered "unformatted" simply if the output of this process differs from the original file's content. Because of this, we can't point to a specific "rule" that was broken; the entire file is just not in the canonical Mago style.

Linter (mago lint)

When the output is large, maybe use a cli pager like less automatically if it's installed, not sure about this one.

Great idea! Using a pager for large output is a good quality-of-life improvement. We'll definitely look into implementing this.

When reviewing issues, I would like to know to disable them...

We can certainly make this clearer in the output. There are two ways to disable a lint rule:

1. Globally in your mago.toml:

   [linter.rules]
   # Example: disable the `no-empty-comment` rule completely
   no-empty-comment = { enabled = false }

   (See: Linter Configuration Reference

2. Inline for a specific line of code:

   /**
    * @mago-expect lint:no-empty-comment
    */
   function foo(): void {
      //
      //
   }

   A great feature here is that Mago will warn you if a suppression comment ( @mago-expect ) is no longer needed, so you can safely remove it!

Not clear how to auto-fix, show which cmd to use for auto-fixing.

Good point, we should add a hint to the output. Auto-fixing is done using the --fix flag. For example, to fix only a specific issue, you could run:

mago lint --only no-empty-comment --fix

Note that not all rules currently provide an automatic fix.

Analyzer (mago analyze)

Same feedback as lint, show how to disable each rule.

Disabling analyzer issues is a bit different as it's not rule-based. You can do it in your mago.toml:

[analyzer]
# Ignore an entire category of issues
redundancy-issues = false

# Ignore a specific error code across the whole project
ignore = ["mixed-argument"]

(See all issue categories here: Analyzer Configuration Reference)

Seems to not find classes outside of this directory...

Yes, this is a common point of confusion that we are actively working to fix!

You've correctly identified the current behavior: when you provide paths to the mago analyze command, it overrides your entire [sources] configuration. This means it sets paths to just what you provided and wipes out includes (like vendor), which is why it can't find classes from the rest of your project.

Our plan is to change this. The command-line paths will override sources.paths, but we'll intelligently move your original sources.paths into sources.includes. This way, the analyzer will focus on reporting issues only in the directories you specified, while still scanning the rest of your project for symbol definitions.

---

Again, thank you for this incredibly detailed feedback. This is exactly what we need to improve the user experience. We've created tickets to track these suggestions and are excited to get them implemented.

[azjezz]

Pager has been implemented, will be released in the next beta 💛

f7b5a79