Is GritQL open source though?

We are planning to open source it.

Thanks @fbartho , that’s a great use case! I suspect if we wanted to enable such a plugin, it might be more convenient if we give formatter plugins access to the JS API too. But could be @morgante has a good idea how to solve this with pure GritQL :)

This would definitely be solvable with pure GritQL, since it's mostly just rearranging a list based on some properties within it.

@morgante I didn’t reply on this last year, but I think it’s slightly more complex than just sorting the list.

It also:

• sorts the fields internally within the import expression — preserving comments
• avoids sorting across a side-effect-only import “polyfill-foo”; — (critical)
• merges multiple import expressions that reference the same source — (required)
• injects blank lines to group imports — (necessary for matching coding-styles)
• splits import expressions (optional configuration for splitting type-imports from side-effect/runtime imports, could probably be dropped)

That's all doable.

Do you have an example that is similar to the sorting list now, as an illustrationi?

I feel you’re misunderstanding the intentions of what Biome is trying to achieve with their custom type inference. It’s there to power lint rules, not to implement a type checker.

It will indeed use “type flow analysis” to do that.

The other alternative for that is to directly interface with the TypeScript language server.

As mentioned in the RFC, someone is investigating this angle as well.

This is what I've been arguing, and while I respect the official effort and want to see how far it gets, I'm looking into integrating actual TypeScript support for type-aware rules. Josh Goldberg (typescript-eslint maintainer) has been helping out, and I've also chatted with Ben about possibly integrating his Ezno checker (which is a WIP Rust TypeScript alternative) in the long run.

Interfacing with the language server is something I want to explore though there'd still need to be support for static runs outside of an IDE context - I also have some concerns regarding how rules are authored since, in typescript-eslint, they rely on the TypeScript compiler API and I'm not sure how much of that is available through LSP (including the upcoming assignability check APIs that the typescript-eslint folks are waiting on).

It's not my decision if Biome wants to use GritQL or not. If anyone has questions about how Grit works, I'm happy to engage. If Biome wants to use Grit, we're happy to collaborate. Otherwise, I don't think I need to defend against incorrect assumptions about how it works.

@morgante

This isn't a technical comment, but it's a comment about your engagement with a member of our community. I have read all the thread, plus all the messages that were edited. I think you have taken this too personally and interacted with them inappropriately.

I would like to keep things technical without judgement and accusation. Jamie's first message looked like neutral and technical to me, based on his knowledge that he gathered from your documentation - here, I assume that the documentation was written by you or one of your collaborators -, and he draw his own conclusions, saying that GritQL might not add enough value as a linter to a Biome plugin system.

Your first response:

Why are you speculating about what GritQL can and cannot do without spending time learning it? We certainly have many rules that look at control flow and scopes.

This tone seems personal to me. If the documentation you - yourself and your collaborators - wrote doesn't provide all the cases that you claim grit provides, I would expect a message that explains it.

Also, I want to assume that your documentation has everything, but it's also possible that a user cannot reach a specific chapter of the documentation. If the user doesn't read something, it's also possible that some parts of the documentation aren't visible. It's fine to share the part of the documentation that the user didn't read, but it's not fine to say:

again affirms you haven't spent any time to understand what you're disparaging

You should teach us about your tool, with an informative tone without being personal. Let's have a technical discussion. You should not be degrading other people for not reading your documentation enough. Maybe your documentation isn't clear enough?

As a maintainer of Biome and Astro, and Rome and webpack-cli in the past, I understand the frustration, but we should never judge other users for not knowing a tool.

This is a formal warning, and I expect an apology to our user Jamie.

I don't think it's a good idea to continue polluting this thread with debates over tone, so I can follow up about that elsewhere.

I'm sorry for my part in dragging things in that direction, and apologize to Jamie for being overly aggressive in my reaction.

In order to make JS plugins fast, Biome is going to need to add a querying system. You've already mentioned one in the RFC. If anything I think it's not ambitious enough. This querying system should be designed as an actor model, it should operate at a higher abstraction level, and it should only pull in parts of the AST that it actually requires. Much like how the green tree works already.

If Biome has its own querying system, the plugin API becomes by design extensible and can change as Biome grows into supporting more use cases, whereas embedding a DSL like GritQL limits Biome to the capabilities of that DSL. It looks to me to be a safer path if one wants to be able to properly react to unknown unknowns. Those are bound to happen as Biome grows into a bundler, a type-checker, a test runner and whatnot.

+1, love the idea of bundling linter deps in the repo too, it simplifies things and works well for Yarn v2+.

Expecting biome to be installed on the system before the user's normal package manager executes is not a convenience (IMHO) for many CI approaches, you end up having to add another CI step, and an out-of-band versioning management issue.

If this project is meant to format JS/TypeScript + NodeJS projects, it should be fair to install it as a node_module

Not requiring node_modules does not imply that Biome (and plugins) can't also be installed via your normal package manager. This is already true today: Biome is available as a standalone executable, but also installable from npm. I don't think anything with plugins would change that.

I guess I was just alarmed by a mix of details in other threads: embedding Deno, having biome install its own plugins, soon you have to manage a lock file for biome, and security disclosures need to go into GitHub etc.

Hehe, no worries. I expect Biome plugins would simply be checked into your repository, similar to how Yarn plugins also work. That means you wouldn’t need a separate install step for them and lockfiles are also not necessary.

It’s also similar in approach to if you use the ESLint rulesdir plugin where you simply specify a directory to load custom rules from.

There are many options to asses: Libjs, njs, Boa, llrt, workerd, ...

Boa seems an interesting candidate indeed. It's written in Rust and its implementation is split into a few crates. Maybe we could cherry-pick a few of the crates to build something tightly integrated with the rest of Biome. Worthy of some more investigation!

FWIW, I don't think I'd be comfortable integrating Hermes into Biome

Actually, what we should consider is static Hermes, which has a different purpose. It's not oriented to react native

@ematipico As cool as I think Static Hermes is (very), I don't think it's suitable for this use case. It's basically a full compiler for translating JS (and to some extent: TS) into C and then to native binaries. Doing that on-demand would give terrible latency, since you'd always have a full compile step before being able to run anything. That's all fine for mobile apps, where you can use regular Hermes during development and then compile binaries for final distribution, but I don't think it makes for a decent plugin system. There's a couple of problems here that I see:

• Bundling Hermes and LLVM with Biome would probably make our binary even bigger than bundling V8.
• The latency for compiling on-demand would be manifold of what any JIT compiler can offer.
• Checking in binaries isn't really a workable solution, since they're platform-specific and would give issues for teams that use multiple operating systems (including teams on Mac who use Linux runners in CI).
• Developing plugins would become very tedious if you have to compile them for every dev-test cycle. You'd be combining the downsides of static languages (slow compilation) with the downsides of dynamic languages (no type safety). Like mobile apps, that wouldn't be an issue if we had regular Hermes as an option as well, but then we need to implement two runtimes...

The Boa devs seems quite receptive to the idea of using their engine in Biome btw: boa-dev/boa#3673

I would not underestimate the importance of manual memory management and Rust's performance. For example, Biome's parsing mechanisms (see biome_rowan/etc) do not currently exist in any JavaScript parser and I believe if someone tried to build one it would be unreasonably slow for tooling that rapidly edits these trees.

I would also not underestimate the weight of serialization between Rust and JavaScript or the limitations you'd need to impose that would make JavaScript plugins notably less powerful than Rust ones. I don't think you could reasonably implement "real-time" typing features with invalid programs and such, you'd need to wait for a valid AST all the time because the cost of the CST would be far too high.

Requiring bundled code could also improve performance for loading and executing code.

Why do you say “Biome doesn’t need to support plugins importing npm dependencies”?

I disagree — declaring that all plugins can’t have dependencies severely limits the problems that can be solved, or the scale of the plugins ahead of time.

That might be an appropriate choice, but I don’t think that’s an “obvious” constraint that can “just” be stated as fact.

At the minimum plugins will need an API surface area from biome, and people like to use their own tools and helpers, those might be external dependencies.

Why do you say “Biome doesn’t need to support plugins importing npm dependencies”?

NPM deps can be bundled, so biome doesn't need to support resolving NPM/node_modules imports.
I'm not saying plugins shouldn't use NPM packages.

Ex. here's an example of how easy it is to subvert any of the built-in rules.

These limitations have nothing to do with GritQL. Biome, as it is today, does not contain type-level information.

GritQL is a query engine on top of the graph. It can query whatever information is available in the graph. You are holding it to expectations that no other linter currently follows.

If you would like to add more semantic information to be available for querying, by all means add it.

I'm probably misunderstanding the tool here. Looking at the documentation for GritQL made me think it is a pattern matching and query tool for only the syntax tree, and that it does not have the ability to represent richer semantic details like "what line of code defines the symbol?".

There is clearly a difference between the "biome graph" and the AST which I missed and I think you were trying to convey above. I think it would help my intuition a ton to see an example of GritQL on a structure which is not merely AST such as the overlaid dataflow you mention:

We have actually had other graphs overlaid on top (ex. dataflow graph) and would like to expose any graph's Biome already has for fast/easy querying. There is nothing intrinsically saying GritQL can only query ASTs.

As for your statement on my semi-obfuscated code:

In general, I really think you should consider what you're trying to do with your tools. If you repo contains code like this then that is the problem

I agree that my example is unreasonable code. There will be unreasonable code and I'm trying to wrap my head around how that works with query-based rules. Your example is a good one, and rightly demonstrates that the current status quo is nothing to write home about, so perhaps I'm thinking too far outside the box!

Looking at the documentation for GritQL made me think it is a pattern matching and query tool for only the syntax tree, and that it does not have the ability to represent richer semantic details like "what line of code defines the symbol?".

That is just semantic information, which could theoretically always be overlaid on top of an AST. Ultimately the AST is what any tool starts with which you can enrich with additional symbolic information.

For example, here's how you can match on the type of a symbol in GritQL if a type tree is available:

`$symbol` where {
   $x = type($symbol),
   $x <: string // match any case where the type of $symbol is resolved as a string
}

Anyways, I think most of your objections are simply with what the state of the art is in most linting tools (including Biome), not GritQL. If Biome ever does add more semantic information, that will be queryable via functions.

There will be unreasonable code and I'm trying to wrap my head around how that works with query-based rules.

I don't know why you are picking on query-based rules. The hard/important part is constructing the semantic tree—once it's available, built-in rules and plugins can both use it.

Anyways I encourage you to consider the purpose of linters is generally to catch common mistakes from developers not to enforce 100% correctness. If you are looking for that, I'm afraid you will be disappointed by ~every tool there is.

I’m sold on query-based rules. It makes sense, once you point out how functions allow for reacting to conditions that are not local, syntactic properties.

And linters don’t prove that things are rigorously, structurally true of code. Because when an engine gets that persnickety, we call it a type system instead :-).

Because when an engine gets that persnickety, we call it a type system instead :-).

Indeed. Hopefully Biome will eventually integrate one, but it's quite a ways off.

Hi @alexgorbatchev, we definitely agree those kinds of rules are important (especially for large/enterprise repos) and fully support them in GritQL.

If you have example rules that you could share, that's always helpful for validating.

Hi @alexgorbatchev, have you tried configuring ESLint to use only your team's custom rules and letting Biome handle everything else? Do you think disabling all other ESLint plugins and rules could improve performance?

@gabrielmoreira just 2 cents, I did that at the company I work for but it's a bit upsetting not to be possible to migrate to a single tool as Biome propose to be.

I'm in the same situation as @alexgorbatchev here but with a few custom rules only, so I can share a tiny one.

We have a Remix project which we agreed that, every route that has a loader MUST also export an error boundary it can handle its own error without bubbling to the root error boundary.

// @ts-check
/** @type {import('eslint').Rule.RuleModule} */
export default {
  meta: {
    type: 'problem',
    fixable: 'code',
    docs: {
      description: `Loader + ErrorBoundary`,
    },
    messages: {
      unexpectedProcessEnv: `When exporting a loader, the route must also provide an ErrorBoundary.`,
    },
  },
  create(context) {
    const sourceCode = context.sourceCode;

    let fileHasLoader = false;
    let importGenericErrorBoundaryWasAdded = false;
    let exportErrorBoundaryWasAdded = false;
    let fileHasErrorBoundary = false;
    /**
     * Every page route that renders something must have a default export.
     * If it only has the loader, it means it's an API route so we don't need
     * to have an ErrorBoundary
     */
    let hasDefaultExport = false;

    return {
      ExportNamedDeclaration(node) {
        if (node.declaration) {
          // Handle FunctionDeclaration (including async functions) and VariableDeclaration
          if (
            node.declaration.type === 'FunctionDeclaration' ||
            node.declaration.type === 'VariableDeclaration'
          ) {
            // For FunctionDeclaration, the function name is directly available
            if ('id' in node.declaration && node.declaration.id.name) {
              if (node.declaration.id.name === 'ErrorBoundary') {
                fileHasErrorBoundary = true;
              } else if (node.declaration.id.name === 'loader') {
                fileHasLoader = true;
              }
            }

            // For VariableDeclaration, iterate through declarations to find the names
            if ('declarations' in node.declaration) {
              for (const declaration of node.declaration.declarations) {
                if (declaration.id && 'name' in declaration.id) {
                  if (declaration.id.name === 'ErrorBoundary') {
                    fileHasErrorBoundary = true;
                  } else if (declaration.id.name === 'loader') {
                    fileHasLoader = true;
                  }
                }
              }
            }
          }
        }

        // Handling other named exports (e.g., export { loader };)
        if (node.specifiers) {
          for (const specifier of node.specifiers) {
            if (specifier.exported && specifier.exported.name) {
              if (specifier.exported.name === 'ErrorBoundary') {
                fileHasErrorBoundary = true;
              } else if (specifier.exported.name === 'loader') {
                fileHasLoader = true;
              }
            }
          }
        }
      },
      ExportDefaultDeclaration() {
        hasDefaultExport = true;
      },
      'Program:exit'(node) {
        if (fileHasLoader && hasDefaultExport && !fileHasErrorBoundary) {
          context.report({
            node: sourceCode.getScope(node).block,
            message: 'When exporting a loader, an `ErrorBoundary` must also be exported.',
            fix(fixer) {
              const { text: fileText, ast } = context.sourceCode;

              let fixers = [];

              if (
                !importGenericErrorBoundaryWasAdded &&
                !fileText.includes("from '$ui/GenericErrorBoundary'")
              ) {
                fixers.push(
                  fixer.insertTextBefore(
                    ast.body[0],
                    "import { GenericErrorBoundary } from '$ui/GenericErrorBoundary'\n",
                  ),
                );
                importGenericErrorBoundaryWasAdded = true;
              }

              if (
                !exportErrorBoundaryWasAdded &&
                !fileText.includes('export const ErrorBoundary')
              ) {
                fixers.push(
                  fixer.insertTextAfter(
                    ast.body[ast.body.length - 1],
                    '\n\nexport const ErrorBoundary = GenericErrorBoundary',
                  ),
                );

                exportErrorBoundaryWasAdded = true;
              }

              return fixers;
            },
          });
        }
      },
    };
  },
};

And it works pretty well as team agreements.

@gabrielmoreira same point of @raulfdm. The entire point of Biome is a single tool. If you have to run Eslint in CI on all your files anyway for your custom rules (knowing that a lot of people are running eslint with prettier) then you're adding yet another thing to the pile, and it would be almost better to stick with what works, rather than migrating to something that neither fully solves all the things that the existing tools with the existing configuration solves, nor provides a reasonable alternative other than simply keeping the old tool around for those use cases, which will still require processing all your files and having to deal with ESLint.

Currently we support neither providing options to GritQL Plugins nor changing the severity of diagnostics. The latter is pretty easy to add while the former needs some discussion.

Gotcha. Without the options I think many of us (or the ecosystem at large) wouldn’t have a migration path from ESLint → Biome for existing projects.

When you think about 1 local plugin working on 1 local project, you could probably get by without options, and just embed the logic directly into GritQL. But the main thing we use is Configs where we ship the same plugin set and default options to multiple projects. Biome also supports sharing configs (extends). And in those instances, if there’s not a way to ship several plugins and default settings to consumers, then the plugins would have to be duplicated and modified in every location, which would be a nonstarter.

If I think about the majority of custom ESLint plugins I’ve worked on or maintained, usually an array of objects is about practically as complex as it ever gets, e.g.:

  rules: {
    'custom/forbid-react-props': [
      'error',
      [
        { propName: 'style', reason: 'No inline styles' },
        { propName: 'tabindex', reason: 'No inline tabindex' },
      ],
    ],
  },

Note: I don’t remember why we wrote a custom version—there were reasons lost to time—but this is just an example and we have a few other plugins that have similar options setups.

I think some reasonable limit could be set on what options are allowed (even assuming Biome’s config file, JSON-serializable options would be 100% OK)! But some projects would forever be stuck on ESLint without this.

nor changing the severity of diagnostics

Oh also worth adding from the GritQL side I generally like the idea of GritQL NOT having any awareness of severity, just a binary pass/fail. It’s just in the configuration being able to set whether this particular diagnostic should fail CI, or just be a warning, but again only the config file knows about this. Same as ESLint.

For example, this could be one suggested modification to the config API (just for illustration purposes, don’t take the details too seriously):

{
  "plugins": {
    // mapping of arbitrary name → plugin location (or npm package)
    "plugin-a": "./plugin-a.gritql",
    "plugin-b": "./plugin-b.gritql",
  },
  "linter": {
    "rules": {
      // alternately, "plugins" or some other name
      "custom": {
        "plugin-a": "error",
        "plugin-b": "warning"
      }
    }
  }
}

In this instance, the GritQL implementation is 100% untouched; it’s only in the configuration that it’s set (and as a bonus, this is a very clean 1:1 migration path from ESLint)

I believe this was answered in the original post up top?

Semgrep and ast-grep both use pattern matching that looks and acts a lot like what GritQL does, although both seem to have a preference for wrapping their patterns in YAML files. We could of course try to take the pattern syntax only, but then we quickly find it to be limited in functionality compared to GritQL's syntax. For instance, where GritQL has direct syntax support for things such as conditions and nested patterns, ast-grep has to fall back to complex-looking YAML structures for more advanced patterns: https://ast-grep.github.io/guide/rule-config.html#rule-file

Finally, it should be mentioned that Morgante, the founder of Grit.io, quickly joined the conversations and showed willingness to cooperate with us. Having their support certainly helped us to confirm our choice.

I would argue that YAML/query language syntax difference is mostly personal taste/project preference. But YAML has several objective benefits:

• easier to learn: no new syntax to learn, just YAML fields in the rule schema
• easier to write: syntax error is harder to make (except YAML's own traps)
• easier editor support: YAML is almost universal. but new query language needs dedicated support for each editor. (lsp won't help since editor does not pick up the file type)
• less effort to build ecosystem: e.g. LSP server (YAML can reuse YAML lsp with json schema), playground (no new syntax to bundle), and probably documentation as well, since more documentation and examples are needed to learn new syntax.

Biome has already made the decision to use gritql, but these challenges are still worth considering for broader plugin adoption.

@Mardoxx can you make an argument against this syntax? The syntax here applies to has, matches, regex, some basic ideas you need to learn regardless of what DSL you pick. Grit has the equivalent thing.

Where can it be more concise or can you make an alternative example in gritql? Does your argument apply the samely to grit as well?

Completely nonsensical without understanding /your own/ DSL.

Does it also apply to gritql?

if you are unhappy with llm polishing my response. I'm sorry about that. and here is my original prompt

Please make this more professional and more constructive. Make it sounds better.

Thanks for the reply. I think the conclusion is clear here and I don't want to pitch further. However I still have some suggestion for bioime to adopt

• YAML. While I see you're trying to dismiss it as a preference, I see it as a fundamental blocker.
  • "creating a DSL anyway" this is how pattern works and it cannot be reduced further. Other YAML APIs are the "essence" of a rule system that you have to teach users, no matter how you design the syntax.
  • YAML makes the syntax part trivial to learn, comparing to DSL where a lot of new syntax of users need to learn and meet a lot of syntax error.
  • for example the code $err <: maybe string(fragment=$fun) => { message: $err } needs a lot of learning and it is not easy to search and needs guessing. Sigil like <: nad => is hard to search. AI can help you guess, but AI can guess YAML better
  • more specifically for grit, it has three categories of concept: pattern, condition, modifiers are harder to distinguish their difference and how to combine them even for one who has expertise in AST.
  • comparing to YAML, the composition rule is very easy: putting a rule object inside another field
  • " you're better off doing it properly than to go halfway.". Every library/tool will need to modeling the problem they need to solve and DSL is not always the answer. e.g. Frontend Frameworks have concepts of hook or signals and they behave differently than plain JS, but it is not a good reason to spin off a new language
• significantly easier to read than ast-grep's mix of DSL and YAML.
• this is subjective. as discussed above, the mental burden of new library is unavoidable. But syntax overhead is avoidable. And also new sigils and compositions are subjectively harder to read.
• even if it is not subjective, readability isn't the main concern for plugin. Since it is not the main code that will be read everyday by every team member. Only infra team or tech lead will implement the rule one time and most of time is using it. In fact, ppl have stronger preference towards JS/TS (due to familiarity and flexibility), though JS/TS plugin are objectively harder to read than pattern DSL or YAML
• in terms of writability, I felt hard to write DSL since I was frequently confused by where to put where or or modifiers. I don't know what's your journey but again it requires significant user education
• writing js/ts plugin with DSL is generally harder than using YAML. YAML is natural extension of JSON so using YAML based rule is trivial in JS/TS plugin. Writing DSL is more like writing SQL in js/ts, you can use

Moving on user education since you already made the decision

• learning new DSL requires a lot of material. Biome should provide it and having examples catalogs
• examples are especially needed since current biome's examples are trivial. I had hard time to implement custom rules without ast-types support. I don't know what's your story but pattern is generally insufficient.
• Q&A and user support are also needed
• documentations currently are insufficient

improve the "Grit with Biome IDE" experience is more than shipping VSCode extension

• broader ecosystem support is needed, e.g. submitting grit support in github
• more editor support: biome plugin should support more editors like vim, sublime, webstorms, each editor needs their syntax detectio for grit
• LSP support: syntax highlighting isn't enough for a good experience. error reporting, completion hovering are also important. biome should also integrate and maintain grit LSP in its CLI.
• TS LSP extensions: if you want to support DSL in js/ts plugin, you should also support template literal highlighting and in-template error reporting and hovering. These require a TS lsp extension.