feat: introduced CLI mode to the parser

canerakdas commented 4 months ago

Description

With this PR, we have added parsing features via CLI.

The following commands you can use: -i, --input <patterns...> Specify input file patterns using glob syntax -e, --exclude <patterns...> Specify patterns to exclude files from being processed -o, --output <path> Specify the output directory path -t, --target <mode> Set the processing mode (default: "mdx") -h, --help display help for command

Just an idea; In the future, we may add verbose to debug logs or silent mode to hide logs 🤔

I left a todo in cli.mjs because I wasn't sure where and how to connect to Parser. I think after #33 is closed, we can determine how we will use it here and organize it
I used Commander.js while preparing this CLI. If there is an alternative that you think might be better, I can try it. It provides many features by default for us to add and test \o/

Validation

First of all make sure the script is executable, after that, you can start to use ./bin/cli.mjs -h

Related Issues

Fixes #3

Check List

[x] I have read the Contributing Guidelines and made commit messages that follow the guideline.
[x] I've covered new added functionality with unit tests if necessary.

ovflowd commented 4 months ago

First of all make sure the script is executable, after that, you can start to use ./bin/cli.mjs -h

I assume with the entry on package.json, if I install this package, how do I run this binary without explicitly doing node bin/cli.mjs -h? How do we define the alias of the binary?

canerakdas commented 4 months ago

First of all make sure the script is executable, after that, you can start to use ./bin/cli.mjs -h

I assume with the entry on package.json, if I install this package, how do I run this binary without explicitly doing node bin/cli.mjs -h? How do we define the alias of the binary?

AFAIK after packing and installing it globally, we can use it with the package name

For example; In package.json, add an example name and version to the package (for example; api-docs-tooling, 0.0.1); You can package the package with npm pack and install and use it globally with npm i -g api-docs-tooling-0.0.1.tgz

ovflowd commented 4 months ago

First of all make sure the script is executable, after that, you can start to use ./bin/cli.mjs -h

I assume with the entry on package.json, if I install this package, how do I run this binary without explicitly doing node bin/cli.mjs -h? How do we define the alias of the binary?

AFAIK after packing and installing it globally, we can use it with the package name

For example; In package.json, add an example name and version to the package (for example; api-docs-tooling, 0.0.1); You can package the package with npm pack and install and use it globally with npm i -g api-docs-tooling-0.0.1.tgz

I'm more concerned on how the binary name is resolved. For example, the package https://www.npmjs.com/package/npm-check-updates is resolved as a binary ncu but the package is actually npm-check-updates (needs to be called as npx npm-check-updates)

canerakdas commented 4 months ago

First of all make sure the script is executable, after that, you can start to use ./bin/cli.mjs -h

I assume with the entry on package.json, if I install this package, how do I run this binary without explicitly doing node bin/cli.mjs -h? How do we define the alias of the binary?

AFAIK after packing and installing it globally, we can use it with the package name For example; In package.json, add an example name and version to the package (for example; api-docs-tooling, 0.0.1); You can package the package with npm pack and install and use it globally with npm i -g api-docs-tooling-0.0.1.tgz

I'm more concerned on how the binary name is resolved. For example, the package https://www.npmjs.com/package/npm-check-updates is resolved as a binary ncu but the package is actually npm-check-updates (needs to be called as npx npm-check-updates)

https://github.com/raineorshine/npm-check-updates/blob/main/package.json#L43-L44

First of all make sure the script is executable, after that, you can start to use ./bin/cli.mjs -h

I assume with the entry on package.json, if I install this package, how do I run this binary without explicitly doing node bin/cli.mjs -h? How do we define the alias of the binary?

AFAIK after packing and installing it globally, we can use it with the package name For example; In package.json, add an example name and version to the package (for example; api-docs-tooling, 0.0.1); You can package the package with npm pack and install and use it globally with npm i -g api-docs-tooling-0.0.1.tgz

I'm more concerned on how the binary name is resolved. For example, the package https://www.npmjs.com/package/npm-check-updates is resolved as a binary ncu but the package is actually npm-check-updates (needs to be called as npx npm-check-updates)

Now I checked, when we want to make a special naming other than the package name, we can show more than one source/target with a different name we want under the bin 🤔

https://github.com/raineorshine/npm-check-updates/blob/main/package.json#L43-L44

In this scenario, we can add the name of the package to @nodejs/api-docs-tooling to follow the same pattern as the website. Also, we can target the binary with different name like this;

  "bin": {
    "api-docs-tooling": "./bin/cli.mjs",
    "adt": "./bin/cli.mjs",
    ... more options
  },

So we can use it in the CLI as api-docs-tooling, adt, or what we want

ovflowd commented 4 months ago

First of all make sure the script is executable, after that, you can start to use ./bin/cli.mjs -h

I assume with the entry on package.json, if I install this package, how do I run this binary without explicitly doing node bin/cli.mjs -h? How do we define the alias of the binary?

AFAIK after packing and installing it globally, we can use it with the package name For example; In package.json, add an example name and version to the package (for example; api-docs-tooling, 0.0.1); You can package the package with npm pack and install and use it globally with npm i -g api-docs-tooling-0.0.1.tgz

I'm more concerned on how the binary name is resolved. For example, the package npmjs.com/package/npm-check-updates is resolved as a binary ncu but the package is actually npm-check-updates (needs to be called as npx npm-check-updates)

raineorshine/npm-check-updates@main/package.json#L43-L44

First of all make sure the script is executable, after that, you can start to use ./bin/cli.mjs -h

I assume with the entry on package.json, if I install this package, how do I run this binary without explicitly doing node bin/cli.mjs -h? How do we define the alias of the binary?

AFAIK after packing and installing it globally, we can use it with the package name For example; In package.json, add an example name and version to the package (for example; api-docs-tooling, 0.0.1); You can package the package with npm pack and install and use it globally with npm i -g api-docs-tooling-0.0.1.tgz

I'm more concerned on how the binary name is resolved. For example, the package npmjs.com/package/npm-check-updates is resolved as a binary ncu but the package is actually npm-check-updates (needs to be called as npx npm-check-updates)

Now I checked, when we want to make a special naming other than the package name, we can show more than one source/target with a different name we want under the bin 🤔

raineorshine/npm-check-updates@main/package.json#L43-L44

In this scenario, we can change the name of the package to @nodejs/api-docs-tooling to follow the same pattern as the website, and on the bin field;
  "bin": {
    "api-docs-tooling": "./bin/cli.mjs",
    "adt": "./bin/cli.mjs",
    ... more options
  },
So we can use it in the CLI as api-docs-tooling, adt, or what we want

cc @nodejs/releasers or @nodejs/build or @nodejs/package-maintenance has there been any other package we published (either internally) with a binary? (I assume yes) and if so, what has been the naming format used?

I'm keen on doing something like node-api-doc or something like that...

wesleytodd commented 4 months ago

has there been any other package we published (either internally) with a binary? (I assume yes) and if so, what has been the naming format used?

I think the main thing I try to consider these days is that npx works as intended, which should mean that using the name of the package is the easiest way. I think you covered this above, but I admit that I mainly just skimmed the above convo.

ovflowd commented 4 months ago

has there been any other package we published (either internally) with a binary? (I assume yes) and if so, what has been the naming format used?

I think the main thing I try to consider these days is that npx works as intended, which should mean that using the name of the package is the easiest way. I think you covered this above, but I admit that I mainly just skimmed the above convo.

Yeah, I also believe the name of the binary should be the name of the package for simplicity and consistency sake. But I wonder what sort of naming conventions are used. Do you have any example, Wes?

ovflowd commented 4 months ago

@canerakdas I believe you can rebase this ;D

nodejs / api-docs-tooling