Helpers that have deep knowledge about the VFS and the environment

[illright]

Issue #69 proposed to remove the Steiger-provided "context" object.

The context should be scrapped. It's currently only used to determine if the source file extension is js or ts, and that is not even implemented yet. Context should be passed to rules through this by binding them upon the plugin creation. That way, only the plugin developer is responsible for what appears in the context. The functionality of exposing certain services to plugin writers will probably be implemented through functions that plugin writers can import.

With this proposal, the meaning of context was redefined:

• previously, "context" meant the context that the linter core has from its knowledge (the filesystem and changes to it, registered rules, all sorts of options)
• now, "context" means the context that the plugin has from its instantiation by the user. For example, if you want to use recommended settings, the plugin author can encode certain decisions that otherwise need deliberation. Another example is if a user wants to customize the plugin by passing options as plugin-wide knowledge, like changing names of FSD layers, the plugin author can transfer these options to all rules through context.

Following this change, we no longer have a way for plugin writers to tap into the knowledge of the linter core. A simple example of why this might be useful is caching information. Currently, the operations of resolving dependencies and extracting imports from a file are done independently by every rule, possibly, several times, if the linter is running in watch mode. This is inefficient, but most importantly, it puts the burden of optimization onto the plugin writers, which causes them to sacrifice developer experience. We strive for the best possible DX, so this should be avoided.

Provide solutions that would enable plugin writers to have convenient access to what the linter knows about the project. Here are the use cases that are on the radar right now:

1. Import resolution
   Accurate import resolution requires finding the right tsconfig.json and resolving aliases
2. Dependency extraction
   Currently done with paperwork, it's a way to get a list of all dependencies of a particular file
3. Preferred language
   For example, if a rule wants to suggest a fix of creating an index file, it needs to know if it should use .js or .ts (or something else entirely)

A future feature, and something to keep in mind, is to let Steiger work with several roots simultaneously, yet independently:

npx steiger ./packages/project1 ./packages/project2

[illright]

Services

The "what"

A service is a special kind of helper that maintains state (cache, mostly). Each service is in tight integration with Steiger core because of how completely different the rules of cache invalidation are. Services are written and maintained by Steiger, which means that plugin writers cannot provide their own services unless they make PRs to Steiger.

A service is preconfigured for each FSD root separately to support monorepos. If we have ./packages/one/tsconfig.json and ./packages/two/tsconfig.json, then running steiger ./packages/one ./packages/two should ensure that imports in one and two are resolved according to their respective tsconfig.json.

flowchart TD
    services ~~~ resolveImport
    plugin ~~~ root[FSD root]
    services -->|for example| resolveImport
    steiger --->|needs to keep up-to-date| services
    plugin -->|needs to use| services
    plugin -->|has access to| root([FSD root])
    root --->|wants preconfigured| resolveImport{{resolveImport}} 
    resolveImport <-->|know when to invalidate cache| steiger

Loading

The "where"

Code-wise, services will be in the steiger package. Two other options would be:

• put them in @steiger/toolkit
  • ➕ plugin authors only need to install @steiger/toolkit and not steiger itself
  • ➖ there's a strong dependency between Steiger and a service — a service needs to subscribe to VFS updates using Steiger's API, and/or Steiger needs to request cache invalidation based on logic that is highly service-specific
• put them in a new package, @steiger/services
  • ➖ plugin authors need to install both @steiger/toolkit and @steiger/services
  • ➖ same downside as putting them in the toolkit — there's a strong link between Steiger and services, so separating them is bad for cohesion

The "how (to use)"

Plugin authors use the services like so:

// plugin/src/rule1.js
import { getServices } from "steiger";
import { createRule } from "@steiger/toolkit";

const rule1 = createRule({
  check(root) {
    const { resolveImport } = getServices(root);
    // …
    const resolvedPath = resolveImport(file1.path, "@/pages/home"); // "/home/project/src/pages/home/index.ts"
  }
});

The "how (to write)"

Steiger registers services as subscribers to the VFS and each service defines for itself what events it wants to act on.

Steiger provides a unified way to access all services for each root — getServices. Services are lazily instantiated for each root and then reused across different rules.

// steiger/src/services/manager.ts, rough concept
import resolveImport from "./resolveImport";

export function getServices(root: Folder) {
  return {
    get resolveImport() {
      // initialize cache if necessary
      return resolveImport.bind(caches[root.path]["resolveImport"])
    }
  }
}

Each service is defined with something like this:

// steiger/src/services/resolveImport.ts
export default function resolveImport(this: ResolveImportCache, pathA: string, pathB: string) {}

export function subscribe(fsUpdate, vfs) {
  // initialize or update the cache or the tracked tsconfig
}