feat: export Ignore symbol

[JounQin]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and discussions and couldn’t find anything or linked relevant results below
• I made sure the docs are up to date
• I included tests (or that’s not needed)

Description of changes

Prepare for mdx-js/eslint-mdx#502

[Copilot]

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

[wooorm]

Needs docs.

[wooorm]

Why do you need this internal API, instead of the package that is used inside?

unified-engine/lib/ignore.js

Line 42 in 579fef8

import ignore_ from 'ignore'

[JounQin]

@wooorm We need resolve .remarkignore, and check API is useful for us.

[JounQin]

Needs docs.

Sure, I'll add after you agree to expose it.

[JounQin]

@wooorm Docs updated.

[JounQin]

@wooorm How about this PR?

[wooorm]

You are using the internal Configuration, now you want the internal Ignore. It sounds like you are reimplementing engine. Why not use engine?

[JounQin]

You are using the internal Configuration, now you want the internal Ignore. It sounds like you are reimplementing engine. Why not use engine?

The linting are executed by file level, the engine runs in project level I think? And I'm pushing a plugin instance for the user automatically at

https://github.com/mdx-js/eslint-mdx/blob/def1f51d4f6ddcf49197258b7b16e5eb49b65f29/packages/eslint-mdx/src/worker.ts#L177

[wooorm]

What is “project level”? What is “file level”?

This package is wrapped in many things. Gulp, Atom, LSP, CLIs.
If you load config files and load ignore files, then you are probably close to this package

[JounQin]

@wooormw As the doc:

engine(
  {
    color: true,
    extensions: ['md', 'markdown', 'mkd', 'mkdn', 'mkdown'],
    files: ['.'],
    ignoreName: '.remarkignore',
    packageField: 'remarkConfig',
    pluginPrefix: 'remark',
    processor: remark,
    rcName: '.remarkrc'
  },
  done
)

It runs only once all through the cli lifecycle, files is an array, sure I could pass a single [file] here, but call engine in every eslint rule for every file once by once seems not correct usage, please point out if I'm wrong.

And with custom Configuration and Ignore, we skip a lot of option check and normalization I think?

[wooorm]

but call engine in every eslint rule for every file once by once seems not correct usage, please point out if I'm wrong.

You are correct, but calling unified() for every lint rule for every file is also wrong.
The main problem is probably “every lint rule”.
“For every file” is fine: you can call engine() for files.

[JounQin]

You are correct, but calling unified() for every lint rule for every file is also wrong.
The main problem is probably “every lint rule”.
“For every file” is fine: you can call engine() for files.

We do have a cache for file at:

https://github.com/mdx-js/eslint-mdx/blob/def1f51d4f6ddcf49197258b7b16e5eb49b65f29/packages/eslint-mdx/src/worker.ts#L145

And as mentioned:

And with custom Configuration and Ignore, we skip a lot of option check and normalization I think?

engine does more than we need, for example, vfile-statistics part, files adn extensions normalizations, finder for files (We're ensured files exist).

[wooorm]

There are caches here too. And if you want better caches, then we can make them. That way, everyone benefits.

engine does more than we need, for example, vfile-statistics part, files adn extensions normalizations.

Very little.
Importantly, you are raising issues/PRs to add more things to the API surface here — so I am not sure about this point.
Normalization of files doesn’t happen if you pass a file.

[JounQin]

There are caches here too. And if you want better caches, then we can make them. That way, everyone benefits.

I'm not sure where it is.

Very little.

Well, I personally prefer skipping funtction calls what we don't need.

Importantly, you are raising issues/PRs to add more things to the API surface here — so I am not sure about this point.

I'm surely understand, but it doesn't hurt, or is there any downsides to export it, I know we should keep API as simple as possible, but I think reusing Configuration and Ignore is a valid use case.

Normalization of files doesn’t happen if you pass a file.

unified-engine/lib/index.js

Lines 305 to 312 in 6f35eae

	// Input.
	settings.files = (options.files || []).map(function (d) {
	const result = isUrl(d) ? fileURLToPath(d) : d
	return result
	})
	settings.extensions = (options.extensions || []).map(function (value) {
	return value.charAt(0) === '.' ? value : '.' + value
	})

[wooorm]

I'm not sure where it is.

Such as this and also #22.

Well, I personally prefer skipping funtction calls what we don't need.

I of course agree.
However, there are different things that make things good. Trade offs.
Another axis is: use APIs instead of copy/pasting internals into your project. You can also make your code better by not implementing everything yourself, but by using engine.

but it doesn't hurt, or is there any downsides to export it

This package exposing hidden internals means that SemVer suddenly applies to them. I can no longer change the internals here without your code breaking.

but I think reusing Configuration and Ignore is a valid use case.

I was reluctantly OK with you using Configuration.
But now you ask for Ignore. Next you ask for FindUp and FileSet and finder.
Making it harder and harder to maintain this package, because I can no longer make internal changes.
Meanwhile you add a lot of code in your package.
Try to use engine! You can remove a lot of code! Measure the speed!

[JounQin]

This package exposing hidden internals means that SemVer suddenly applies to them. I can no longer change the internals here without your code breaking.

@wooorm Maybe we can export an entry use-at-your-own-risk just like eslint. Or just point out they're only for internal usages in document and don't follow semver, or even just don't document them.

But now you ask for Ignore. Next you ask for FindUp and FileSet and finder.
Making it harder and harder to maintain this package, because I can no longer make internal changes.

In the meantime, I won't expect use anything internal else since then, FindUp,finder, etc. are alrady covered by Configuration and Ignore.