Add support for resolveFromAST in plugins

[webpro]

Add support for resolveFromAST in plugins so we can use the source file AST directly (i.e. without loading the file and receiving the resolved localConfig).

Updated plugin guide: https://feat-plugin-ast.knip.pages.dev/guides/writing-a-plugin#example-4-use-the-ast-directly

New plugins:

• TanStack Router (Add @tanstack/react-router plugin #856)
• SST (Add SST plugin #985)
• Starlight

Extended plugins:

• Astro (new plugin: Starlight)
• Next.js

For the existing resolveEntryPaths and resolveFromConfig functions that plugins can implement, Knip loads the tool's configuration file and passes the resulting object to this plugin function. This works well for most cases, but has some drawbacks:

• Potentially slow as it may import lots of dependencies itself
• Error-prone as the config files may depend on context such as environment variables being set
• Information may be missing once resolved i.e. the returning object might no longer contain references we want

An example vite.config.ts:

import { defineConfig } from 'vite';
import { TanStackRouterVite } from '@tanstack/router-plugin/vite';

export default defineConfig({
  plugins: [
    TanStackRouterVite({
      routesDirectory: './routes',
      generatedRouteTree: './gen/routeTree.gen.ts',
    }),
  ],
});

We want to know the values of routesDirectory and generatedRouteTree, but if we import('vite.config.ts') then this information is missing from the default-exported value that we pass on to resolveEntryPaths and resolveFromConfig.

The vite.config.ts is already part of the module graph and it's import statements need to be parsed anyway (so we know vite and @tanstack/router-plugin/vite are dependencies that should be listed in package.json), so why not make this available to plugins as well?

This way, plugins can create a custom function to extract the information, in this case the (new) TanStack Router plugin can return non-default entry paths (./routes/**/*.{ts,tsx}) and a non-default path for generatedRouteTree so users don't need to configure such entry patterns manually in knip.json. This was previously impossible!

A downside is that the "DSL" here is the TS API, which is powerful but also tedious. Another downside is that the plugins can start using typescript dependency which has a large API surface and reduces their compactness and simplicity, which in turn requires more governance.

Here's example code to do what we just described:

import ts from 'typescript';

const CONFIG_KEYS = new Set([
  'routeFilePrefix',
  'routeFileIgnorePrefix',
  'routeFileIgnorePattern',
  'routesDirectory',
  'generatedRouteTree',
]);

const FUNCTIONS = new Set(['TanStackRouterVite', 'TanStackRouterRspack', 'TanStackRouterWebpack']);

export const getCustomConfig = (sourceFile: ts.SourceFile) => {
  const config: Record<string, string> = {};

  function visit(node: ts.Node) {
    if (ts.isCallExpression(node)) {
      const callee = node.expression;
      if (ts.isIdentifier(callee) && FUNCTIONS.has(callee.text)) {
        const firstArg = node.arguments[0];
        if (ts.isObjectLiteralExpression(firstArg)) {
          for (const prop of firstArg.properties) {
            if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
              if (CONFIG_KEYS.has(prop.name.text)) {
                if (ts.isStringLiteral(prop.initializer)) {
                  config[prop.name.text] = prop.initializer.text;
                }
              }
            }
          }
        }
      }
    }

    ts.forEachChild(node, visit);
  }

  visit(sourceFile);

  return config;
};

Also see the other resolveFromAST.ts files in this PR for more examples.

There are no utilities for this type of querying yet, but I can imagine we'll often want to do things like "get the string values of certain literal object properties" so that could be a next step once we figure out our needs better.

Edit: added a few helpers already 😇 so also the example above can be implemented more concise now

Edit 2: also see #1009 that has the same plugins using tsquery

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/knip@1005

commit: 8c0a7fe

[tryggvigy]

Seeing that both plugin.resolveEntryPaths and plugin.resolveConfig attempt to define loadedConfig makes me think they are mutually exclusive properties (don't make sense when specified together in plugin). Is that true? If so, maybe it could be helpful to model the type of plugin to eliminate the invalid state where both can be passed on the same time. I'm just spitballing here really and could be completely off, also this could not matter at all :) I kind of lack the bigger picture. I'll comment on everything where I have some thought. Feel free to disregard any of my comments

[webpro]

resolveEntryPaths and resolveConfig can both be implemented as they server different purposes. They might get merged one day now that we have all the "inputs" (onEntry etc), but that'd be for another day. So what I was trying to do here is "load if need, and skip if not".

[tryggvigy]

Not sure if we want to care about require call expressions here?

import('foo') seems to be a ImportKeyword in TS AST as well. ts.isImportDeclaration probably doesn't catch those

[webpro]

This is specific to SST, so probably not.

[BryanCrotazGivEnergy]

well SST can be used with require or with import...

[webpro]

One does not generally use CommonJS syntax in TS files (sst.config.ts). Or is e.g. sst.config.cjs also supported?

Would be easy to add, though :)

[tryggvigy]

It's another dep which is not great but I wonder if you want something like https://github.com/phenomnomnominal/tsquery to make the AST branching logic a bit more terse.

[tryggvigy]

When building queries https://astexplorer.net/ and https://tsquery-playground.firebaseapp.com/
are very useful.

[webpro]

I've actually looked at tsquery, but what we need is a few matchers, so at this point I'm thinking to create those as we go (indeed, without pulling in another dep).

[webpro]

Thanks for sharing those, I often use https://ts-ast-viewer.com

[cloudflare-workers-and-pages]

Deploying knip with    Cloudflare Pages

Latest commit:	079263b
Status:	✅  Deploy successful!
Preview URL:	https://2ee6f1f4.knip.pages.dev
Branch Preview URL:	https://feat-plugin-ast.knip.pages.dev

View logs

[webpro]

Confident to go in this direction, hence the merge to main.

[webpro]

🚀 This pull request is included in v5.48.0. See Release 5.48.0 for release notes.

Using Knip in a commercial project? Please consider becoming a sponsor.