Skip to content

fix: add hashbang property to AST #183

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
overlookmotel merged 1 commit into from
Feb 24, 2026
Merged

fix: add hashbang property to AST #183

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions src/test262.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ await run({
const isModule = preamble.flags?.includes("module");

let ast;
const comments = [];
try {
ast = AcornParser.parse(code, {
ecmaVersion: "latest",
Expand All @@ -51,6 +52,7 @@ await run({
allowReturnOutsideFunction: true,
// Note: Do not specify `allowAwaitOutsideFunction` option.
// It defaults to `true` for modules, `false` for scripts, which is what we want.
onComment: comments,
});
} catch {
try {
Expand All @@ -63,6 +65,7 @@ await run({
globalReturn: true,
webcompat: true, // I think this enables support for Annex B
next: true, // Enable parsing decorators and import attributes
onComment: comments,
});
} catch {
return;
Expand All @@ -71,6 +74,14 @@ await run({
fixMeriyahValue(ast);
}

// Add `hashbang` property to AST if file starts with a hashbang.
// This property is non-standard and exclusive to Oxc.
if (comments.length > 0 && code.startsWith("#!") && comments[0].type === "Line") {
Copy link

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Potential issue: The check comments.length > 0 && code.startsWith("#!") && comments[0].type === "Line" doesn't verify that comments[0] is actually the hashbang comment at position 0. If there's leading whitespace or other comments, comments[0] might not correspond to the hashbang. Consider adding a check that comments[0].start === 0 to ensure it's the first thing in the file.

Suggested change
if (comments.length > 0 && code.startsWith("#!") && comments[0].type === "Line") {
if (
comments.length > 0 &&
code.startsWith("#!") &&
comments[0].type === "Line" &&
comments[0].start === 0
) {

Copilot uses AI. Check for mistakes.
ast.hashbang = { ...comments[0], type: "Hashbang" };
} else {
ast.hashbang = null;
}

// Parse tokens
const tokensJson = parseEspreeTokens(code, isModule, false);

Expand Down
13 changes: 11 additions & 2 deletions src/typescript-eslint.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,19 @@ await run({
let output = "";
for (const test of tests) {
try {
const result = parseForESLint(test.content, {
// Convert hashbang to normal line comment.
// This is what ESLint does, before passing code to parser.
let code = test.content;
const hasHashbang = code.startsWith("#!");
if (hasHashbang) code = `//${code.slice(2)}`;

const result = parseForESLint(code, {
filePath: path,
sourceType: test.sourceType.module ? "module" : "script",
ecmaFeatures: {
jsx: test.sourceType.jsx,
},
});
// oxlint-disable-next-line no-unused-vars
const { comments, tokens, ...program } = result.ast;

// TS-ESLint parser has no `unambiguous` option, so emulate it here
Expand Down Expand Up @@ -73,6 +78,10 @@ await run({
}
}

// Add `hashbang` property to AST if file starts with a hashbang.
// This property is non-standard and exclusive to Oxc.
program.hashbang = hasHashbang ? { ...comments[0], type: "Hashbang" } : null;
Copy link

Copilot AI Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Potential issue: Assuming that comments[0] is the hashbang comment may not be safe. If the code has leading whitespace or other comments before the hashbang is converted to a comment, this could fail or assign the wrong comment. Consider checking that comments[0].start === 0 to ensure it's actually the first thing in the file.

Suggested change
program.hashbang = hasHashbang ? { ...comments[0], type: "Hashbang" } : null;
let hashbangComment = null;
if (hasHashbang && Array.isArray(comments) && comments.length > 0) {
// Prefer a comment that starts at the very beginning of the file.
const firstCommentAtStart = comments.find((comment) => comment.start === 0);
const baseComment = firstCommentAtStart ?? comments[0];
hashbangComment = { ...baseComment, type: "Hashbang" };
}
program.hashbang = hashbangComment;

Copilot uses AI. Check for mistakes.

const astJson = stringifyWith(program, transformerTs);
output += "__ESTREE_TEST__:AST:\n```json\n" + astJson + "\n```\n";

Expand Down
2 changes: 0 additions & 2 deletions src/utils/json.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,8 +135,6 @@ export function transformerTs(_key, value) {
}

export function stringifyWith(ast, transformer) {
// Add `hashbang` field
ast.hashbang = null;
// Serialize to JSON, with modifications
let json = JSON.stringify(ast, transformer, 2);
json = json.replace(INFINITY_REGEXP, "1e+400");
Expand Down
7 changes: 6 additions & 1 deletion tests/test262/test/language/comments/hashbang/line-terminator-carriage-return.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,12 @@
}
],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": " this comment ends with a Carriage Return (U+000D)",
"start": 0,
"end": 52
},
"start": 0,
"end": 637
}
7 changes: 6 additions & 1 deletion tests/test262/test/language/comments/hashbang/line-terminator-line-separator.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,12 @@
}
],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": " this comment ends with a Line Separator (U+2028)",
"start": 0,
"end": 51
},
"start": 0,
"end": 635
}
7 changes: 6 additions & 1 deletion tests/test262/test/language/comments/hashbang/line-terminator-paragraph-separator.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,12 @@
}
],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": " this comment ends with a Paragraph Separator (U+2029)",
"start": 0,
"end": 56
},
"start": 0,
"end": 645
}
7 changes: 6 additions & 1 deletion tests/test262/test/language/comments/hashbang/module.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,12 @@
"type": "Program",
"body": [],
"sourceType": "module",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": "",
"start": 0,
"end": 2
},
"start": 0,
"end": 333
}
7 changes: 6 additions & 1 deletion tests/test262/test/language/comments/hashbang/not-empty.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,12 @@
"type": "Program",
"body": [],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": " these characters should be treated as a comment",
"start": 0,
"end": 50
},
"start": 0,
"end": 412
}
7 changes: 6 additions & 1 deletion tests/test262/test/language/comments/hashbang/use-strict.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,12 @@
}
],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": "\"use strict\"",
"start": 0,
"end": 14
},
"start": 0,
"end": 391
}
7 changes: 6 additions & 1 deletion tests/typescript/tests/cases/compiler/emitBundleWithShebang1.ts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,12 @@ __ESTREE_TEST__:AST:
}
],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": "/usr/bin/env gjs",
"start": 0,
"end": 18
},
"start": 19,
"end": 59
}
Expand Down
14 changes: 12 additions & 2 deletions tests/typescript/tests/cases/compiler/emitBundleWithShebang2.ts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,12 @@ __ESTREE_TEST__:AST:
}
],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": "/usr/bin/env gjs",
"start": 0,
"end": 18
},
"start": 19,
"end": 60
}
Expand Down Expand Up @@ -206,7 +211,12 @@ __ESTREE_TEST__:AST:
}
],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": "/usr/bin/env js",
"start": 0,
"end": 17
},
"start": 18,
"end": 61
}
Expand Down
7 changes: 6 additions & 1 deletion ...pescript/tests/cases/compiler/emitBundleWithShebangAndPrologueDirectives1.ts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,12 @@ __ESTREE_TEST__:AST:
}
],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": "/usr/bin/env gjs",
"start": 0,
"end": 18
},
"start": 19,
"end": 72
}
Expand Down
14 changes: 12 additions & 2 deletions ...pescript/tests/cases/compiler/emitBundleWithShebangAndPrologueDirectives2.ts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,12 @@ __ESTREE_TEST__:AST:
}
],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": "/usr/bin/env gjs",
"start": 0,
"end": 18
},
"start": 19,
"end": 73
}
Expand Down Expand Up @@ -251,7 +256,12 @@ __ESTREE_TEST__:AST:
}
],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": "/usr/bin/env gjs",
"start": 0,
"end": 18
},
"start": 19,
"end": 94
}
Expand Down
7 changes: 6 additions & 1 deletion tests/typescript/tests/cases/compiler/shebang.ts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,12 @@ __ESTREE_TEST__:AST:
}
],
"sourceType": "script",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": "/usr/bin/env node",
"start": 0,
"end": 19
},
"start": 20,
"end": 79
}
Expand Down
7 changes: 6 additions & 1 deletion tests/typescript/tests/cases/compiler/shebangBeforeReferences.ts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,12 @@ __ESTREE_TEST__:AST:
}
],
"sourceType": "module",
"hashbang": null,
"hashbang": {
"type": "Hashbang",
"value": "/usr/bin/env node",
"start": 0,
"end": 19
},
"start": 53,
"end": 123
}
Expand Down