feat(utils): add shebang

[AugustinMauroy]

Description

Introducing new utilities to manage args in shebangs

Related issue

Related to #94

[JakobJingleheimer]

I think this is actually not the correct behaviour: I think it's first-wins (not last-wins). I couldn't quickly find an authoritative source specifying what happens, but a quick search pulls up many StackExchange answers all claiming this, as well as some blogs. I didn't find anything that claims anything else.

[AugustinMauroy]

it's why

[JakobJingleheimer]

Yeah, it's telling you all the ones after the first are invalid.

[AugustinMauroy]

so it's maybe an tree-sitter/ast-grep issue

[JakobJingleheimer]

Maaaaybe? This shebang util is invalid until whatever the issue is is fixed 😥

[HerringtonDarkholme]

Hi, the issue comes from tree-sitter parser's implementation. The grammar only supports one single hashbang line. See

https://github.com/tree-sitter/tree-sitter-javascript/blob/58404d8cf191d69f2674a8fd507bd5776f46cb11/grammar.js#L156-L162

This is correct grammar according to the spec, https://tc39.es/ecma262/#sec-hashbang, the shebang appears only at the top of a module/script and should be only oneline. https://github.com/tc39/ecma262/pull/2816/changes

That said, the tree-sitter error recovery is treating the last hash_bang_line as correct instead of the first.

[JakobJingleheimer]

I would probably add a second, optional arg for replacements so users can do it in one go like:

const sb = getShebang(…, { foo: 'bar' });

instead of

const sbRaw = getShebang(…);

const sb = replaceNodeJsArgs(sbRaw, { foo: 'bar' });

I would keep replaceNodeJsArgs as a separate function that getShebang calls internally when the second arg is present.

[AugustinMauroy]

that was designed like package.json utilizes:

/**
 * Replace Node.js arguments in the "scripts" node of a package.json AST.
 * @param packageJsonRootNode The root node of the package.json AST.
 * @param argsToValues A record mapping arguments to their replacement values.
 * @param edits An array to collect the edits made.
 */
export const replaceNodeJsArgs = (packageJsonRootNode: SgRoot, argsToValues: Record<string, string>) => {

[JakobJingleheimer]

Hmm? I don't understand

[AugustinMauroy]

I don't get your proposition here.

We will have twoo function called replaceNodeJsArgs one in shebang utility and the other in the package json utility which already exist and they will be called in different context but I want to have same signature for these functions for a better DX

[JakobJingleheimer]

If the other one doesn't deal with replacements, then keeping the same signature doesn't really fit. If the other one does deal with replacements, then they should both do it 🙂

[AugustinMauroy]

IDK what is the best

[JakobJingleheimer]

this was more of a nit; it's an additive change (non-breaking), so it could be addressed later.

[HerringtonDarkholme]

I think a reasonable fix here would be find the first hash_bang_line in the tree.

According to the grammar spec

There are several situations where the identification of lexical input elements is sensitive to the syntactic grammar context that is consuming the input elements. This requires multiple goal symbols for the lexical grammar. The InputElementHashbangOrRegExp goal is used at the start of a Script or Module.

[JakobJingleheimer]

🙌