Content mappers: more granular resolution, and default extensions in the manifest

Start by tracing the content-mapper initialize and transform protocol, then inspect typescript.contentMapper manifest handling and tsconfig registration. Compare the proposed filter, claim, and default-extension behaviors and determine which design is selected. Done means the chosen resolution and registration rules are specified with corresponding coverage.

Some feedback on content mappers, based on a few limits I hit.

More granular resolution

I'm imagining a framework (let's call it "blob") with a file system router and a root config file called blob.toml. It would be cool to be able to "import" the router as a tRPC-style SDK. The obvious thing would be to import blob.toml as the "entrypoint" of the framework and get back that SDK. Perhaps this is seen as a total abuse of content mappers...but it would be cool!

Currently, since the entire system is based on extensions, you can't define one that has special handling for a file specifically called blob.toml. You'd have to register a content mapper for all TOML files, in which case no other TOML loading is possible.

Recommendations:

• Support regex-style matching a la esbuild onResolve/filter. In the current protocol this could be a field on the initialize result, tested against the absolute path of any file whose extension the mapper registered:

  interface InitializeResult {
      positionEncoding: PositionEncoding;
      diagnosticSource: string;
      /** RE2 syntax, like esbuild. When present, the mapper only receives files matching it. */
      filter?: string;
  }
  

  The same field in the typescript.contentMapper manifest would let TypeScript apply it without starting the process.

• Allow a dynamic onRegister-style API where a mapper can choose to resolve or not resolve based on the path, etc. In the current protocol this could be a content-free request sent before transform, with several mappers allowed on one extension and tried in contentMappers order until one claims the file:

  interface ClaimParams {
      fileName: string;
      projectHandle: string;
  }
  
  interface ClaimResult {
      claimed: boolean;
  }
  

  Content-free matters here, because a mapper that declines most files should not pay for their contents.

• A names list alongside extensions (not my preference).

Default extensions in the manifest

If you let a content mapper define a default extensions list, the onus isn't on the user for this. I suspect these user-specified extensions lists will be pretty redundant in most cases (e.g. a content mapper called toml-loader that only ever loads TOML).

If extensions becomes optional, and the config/options object is also often optional, the registration in tsconfig can reduce to a simple string for the simple (and common) case.

"contentMappers": ["mdx-content-mapper"]