Remark config type safety

[jaydenseric]

How are you supposed to type Remark config with TypeScript flavor JSDoc comments?

For example, in .remarkrc.mjs:

// @ts-check

/**
 * Remark configuration.
 * @satisfies {import("?").?}
 */
const remarkConfig = {
  plugins: ["remark-lint", "remark-lint-heading-increment"],
};

export default remarkConfig;

In that code example, what should the ? placeholders be?

considering the only direct dev dependencies I have added to the project is remark-lint and remark-lint-heading-increment, an ideal solution would:

• Only import types from those direct dependencies and not refer to a transient dependency so I don't have to add it to my package's dev dependencies (it's bad practice to import from packages that are not declared dependencies of your project's package).
• Only have types for the relevant Remark plugins I have installed, i.e. in settings only available settings should be typed.

[ChristianMurphy]

Hey @jaydenseric! 👋
Each configuration file is creating a Preset https://github.com/unifiedjs/unified-engine?tab=readme-ov-file#preset

[jaydenseric]

Hi!

It's not clear reading those preset docs what my @satisfies {import("?").?} should be, in my code example. Are you able to provide example code for the @satisfies?

Could you expand more on what you mean with this?
How would TypeScript be aware of direct vs transitive dependencies?

As a general rule, anything you import in your code is a direct dependency, and must be declared in your package with a version range. It's an established enough best practice that there are lint rules in the ecosystem to enforce this, e.g:

https://github.com/import-js/eslint-plugin-import/blob/fc361a9998b14b9528d841d8349078a5af2da436/docs/rules/no-extraneous-dependencies.md

It's should be self-evident the reasons why you need to declare your program's dependencies; I could explain some but that's kind of beyond the scope of what I have time for in this question/discussion. Transient dependencies are not part of the semver contract packages have; they are free to drop them or update major versions etc. at will as an implementation detail in minor or patch releases, as long as the package's declared public API isn't affected. If you are relying by pure coincidence on a transient dependency being installed at a particular version, via some other dependency, then it's very fragile and your code could break a lot over time. It also makes it hard to tell as a human what a projects dependencies are when reading the package file if some are undeclared.

As long as the parser/stringifier/plugins that interact with the settings object are referenced this will happen automatically.

Can you please show how to do that in my example config code? Via a triple slash reference comment at the top?

[ChristianMurphy]

https://github.com/import-js/eslint-plugin-import/blob/fc361a9998b14b9528d841d8349078a5af2da436/docs/rules/no-extraneous-dependencies.md
It's should be self-evident the reasons why you need to declare your program's dependencies; I could explain some but that's kind of beyond the scope of what I have time for in this question/discussion. Transient dependencies are not part of the semver contract packages have; they are free to drop them or update major versions etc. at will as an implementation detail in minor or patch releases, as long as the package's declared public API isn't affected. If you are relying by pure coincidence on a transient dependency being installed at a particular version, via some other dependency, then it's very fragile and your code could break a lot over time. It also makes it hard to tell as a human what a projects dependencies are when reading the package file if some are undeclared.

Right, I get the why, and agree on the front of lint and validate as much as possible.
I also think you somewhat answered your own question here, use ESLint.
TypeScript isn't aware of your package.json, maybe you could find a way to make it do ESLint like stuff, but why not just use ESLint? 😅

Can you please show how to do that in my example config code? Via a triple slash reference comment at the top?

Using a reference directive https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html#-reference-path-

for example

remark/packages/remark/index.d.ts

Lines 1 to 2 in 8ca9469

	/// <reference types="remark-parse" />
	/// <reference types="remark-stringify" />

It's not clear reading those preset docs what my @Satisfies {import("?").?} should be, in my code example

Using the repo and the type linked in my last comment, to make that more concrete.

/**
 * @satisfies {import("unified-engine").Preset}

[jaydenseric]

I also think you somewhat answered your own question here, use ESLint.
TypeScript isn't aware of your package.json, maybe you could find a way to make it do ESLint like stuff, but why not just use ESLint?

There might be some confusion; ESLint isn't to do with the question raised in this discussion. I only referenced a community ESLint rule that enforces no imports from transient dependencies as evidence that it's a best practice. Right now, the code examples for installing and configuring Remark via JavaScript don't show:

• How to do JSDoc type safety in the config module.
• The npm install instructions don't show that all the packages being referenced or imported from in the config module should be installed as dev dependencies (to avoid the anti-pattern of importing from transient dependencies).

Because it's such an awkward thing, to reference and import from dependencies of dependencies in your config module, I think the API design could do with an overhaul. I would like to be able to import types from just the dev dependencies I install, to be able to configure those dev dependencies with type safety.

I have tried your suggestions, and ran into TS errors with this .remarkrc.js

// @ts-check
/// <reference types="remark-parse" />
/// <reference types="remark-stringify" />

import remarkLintHeadingIncrement from "remark-lint-heading-increment";

/**
 * Remark configuration.
 * @satisfies {import("unified-engine").Preset}
 */
const remarkConfig = {
  plugins: ["remark-lint", remarkLintHeadingIncrement],
};

export default remarkConfig;

The plugins key has this TS error:

  Type '(string | { (config?: unknown): ((tree: Root, file: VFile, next: TransformCallback<Root>) => undefined) | undefined; readonly name: string; })[]' is not assignable to type 'PluggableListSupportingSpecifiers'.    Type 'string | { (config?: unknown): ((tree: Root, file: VFile, next: TransformCallback<Root>) => undefined) | undefined; readonly name: string; }' is not assignable to type 'PluggableSupportingSpecifiers'.      Type '{ (config?: unknown): ((tree: Root, file: VFile, next: TransformCallback<Root>) => undefined) | undefined; readonly name: string; }' is not assignable to type 'PluggableSupportingSpecifiers'.        Type '{ (config?: unknown): ((tree: Root, file: VFile, next: TransformCallback<Root>) => undefined) | undefined; readonly name: string; }' is not assignable to type 'Plugin'.          Type '((tree: Root, file: VFile, next: TransformCallback<Root>) => undefined) | undefined' is not assignable to type 'void | Transformer<Node, Node> | undefined'.            Type '(tree: Root, file: VFile, next: TransformCallback<Root>) => undefined' is not assignable to type 'void | Transformer<Node, Node> | undefined'.              Type '(tree: Root, file: VFile, next: TransformCallback<Root>) => undefined' is not assignable to type 'Transformer<Node, Node>'.                Types of parameters 'tree' and 'tree' are incompatible.                  Property 'children' is missing in type 'Node' but required in type 'Root'.

If you replace remarkLintHeadingIncrement with the string "remark-lint-heading-increment", the type error goes away. But only because you are opting out of type safety. I actually will be using the string form in my real config, but am using the JS way of including the plugin the make reproducible the same TS error I encounter when attempting to configure my custom local plugin, which is imported and specified in the config via JS. It has similar typings to the official lint rule plugins.

[wooorm]

ESLint isn't to do with the question raised in this discussion

raising a question about something, implies that the answer is unknown; so if you don’t ask about eslint, it might very well be that the answer is about eslint.

Right now, the code examples for installing and configuring Remark via JavaScript don't show:

• How to do JSDoc type safety in the config module.
• The npm install instructions don't show that all the packages being referenced or imported from in the config module should be installed as dev dependencies (to avoid the anti-pattern of importing from transient dependencies).

Which examples do you mean?
How to use JSDoc correctly seems like something for the TypeScript website, or other resources, not something that we need to explain when describing one option for a config file format?
Which npm install instructions do you mean?
There are different ways to use all the tools together, sometimes as dependencies (when sharing a preset), sometimes as dev-dependencies.

I would like to be able to import types from just the dev dependencies I install, to be able to configure those dev dependencies with type safety.

Whether to include typescript dependencies in dependencies or devDependencies depends more on how TypeScript generally works.
Are you publishing the generated .d.ts files, and will those .d.ts files include imports to these packages? Then you need dependencies.
Otherwise, you can use devDependencies

But only because you are opting out of type safety.

The difference is not type safety.
For both, there is no check between the plugin and its options.
Both are “unsafe”, if you will.
Or, one might say, unchecked.

If you replace remarkLintHeadingIncrement with the string "remark-lint-heading-increment", the type error goes away.

Sometimes, the disappearance of a particular error, does not mean an improvement.
I think the error is a bug in unified-engine, of the Preset type. It should accept all plugins, whether strings or functions.
I think the problem is because the plugin expects a specific mdast (markdown) node, whereas unified-engine expects the vague, abstract, unist node.

---

Type checking plugins and options is quite complex. The unified internals are very complex.
And that is without presets (of which this settings “preset”, is a version, it allows package names/file paths too, that‘s the only differents).
Your root problem is similar to unifiedjs/unified#221, which I don‘t think can be really solved.

Still, coming back to your root problem, of how to type your config file, I would go with:

/**
 * @import {PluginTuple, Preset} from 'unified'
 */

import remarkLint from 'remark-lint'
import remarkLintHeadingIncrement from 'remark-lint-heading-increment'
import remarkLintCheckboxCharacterStyle from 'remark-lint-checkbox-character-style'
import remarkLintCodeBlockStyle from 'remark-lint-code-block-style'

/**
 * My remark preset.
 *
 * @satisfies {Preset}
 */
const remarkPresetJayden = {
  plugins: [
    remarkLint,
    remarkLintHeadingIncrement,
    /** @type {PluginTuple<[import('remark-lint-checkbox-character-style').Options]>} */
    ([remarkLintCheckboxCharacterStyle, 'consistent']),
    /** @type {PluginTuple<[import('remark-lint-code-block-style').Options]>} */
    ([remarkLintCodeBlockStyle, 'asdasdasd'])
  ]
}

export default remarkPresetJayden

This shows two plugins with options: the first correct, the second incorrect. The first is typed okay, the other has a type error. Showing “type safety”.

Furthermore, this uses a regular unified preset, where you load packages yourself. That means you can use this generally in JavaScript, everywhere you want.

Finally, for this, make sure to install, as dependencies, unified, remark-lint, remark-lint-heading-increment, remark-lint-checkbox-character-style, and remark-lint-code-block-style.

[ChristianMurphy]

Right now, the code examples for installing and configuring Remark via JavaScript don't show:

• How to do JSDoc type safety in the config module.
• The npm install instructions don't show that all the packages being referenced or imported from in the config module should be installed as dev dependencies (to avoid the anti-pattern of importing from transient dependencies).

Which examples do you mean?
How to use JSDoc correctly seems like something for the TypeScript website, or other resources, not something that we need to explain when describing one option for a config file format?
Which npm install instructions do you mean?
There are different ways to use all the tools together, sometimes as dependencies (when sharing a preset), sometimes as dev-dependencies.

Adding on. I assume the documentation being referenced here is a readme.
A readme's goal is to educate how to use this project.
A lot of the unified/remark readme's are already pretty information dense.

I'm cautious adding more information about best practices of external tooling because:

• It risks overloading an already information dense document
• We have a separate area of docs https://unifiedjs.com/learn/ which is designed to cover more advanced topic and topics which cross multiple projects.
• Adding the best practices external tooling is a bit of a snowball effect problem, there is so much tangential information that could be included
• There are 300+ readmes in the unified ecosystem, that is a lot of places to update with information not specific to the project

ESLint isn't to do with the question raised in this discussion

raising a question about something, implies that the answer is unknown; so if you don’t ask about eslint, it might very well be that the answer is about eslint.

It feels like the ask is for remarkjs to essentially enforce your eslint config.
We use xo internally, but don't force downstream packages to use that tool/config.

Type checking plugins and options is quite complex. The unified internals are very complex.
And that is without presets (of which this settings “preset”, is a version, it allows package names/file paths too, that‘s the only difference).
Your root problem is similar to unifiedjs/unified#221, which I don‘t think can be really solved.

It may be possible, there are some partial solutions linked in unifiedjs/unified#221
Given enough time and typescript expertise (and potentially some upstream typescript contributions) it may be possible.
It's pretty low in my queue to look into this again, but if you, @jaydenseric, feel passionate about more strongly typing these, feel free to dig into it and explore options and offer PRs.