You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 7963bb8
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/syntax.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,6 +38,6 @@ Read this before touching the CSS, HTML or JavaScript parser, printer or minifie
38
38
39
39
-`syntax.js` reaches `parser` and `printer` through getters: parsing never loads the printer, and the printer loads the parser for its `parse` phase, which reads an asset with it — building the printer's tree as each statement finishes, rather than converting a tree. It is the only parser: a source it refuses is refused, and terser's parse options for what is not a program (`parse.expression`, `parse.strict`, `parse.experimental_typescript`) are refused too.
40
40
-`syntax-parser.js` — tokenizer, acorn-derived core and every production in one file (any parse reaches the productions, and the coming struct-of-arrays rewrite moves node creation through them). `regexp.js` (pattern validator) is the one on-demand piece, reached only for a pattern the host engine rejected — never `require` it from a build path.
41
-
- `syntax-printer.js` — webpack's JavaScript minifier, terser's design ported to write byte for byte what terser writes; `jsMinify.js` is the `minify` the default minimizer dispatches JS to under `experiments.futureDefaults`, and goes through it alone; without that flag the minimizer dispatches to `terserMinify` as `minimizer-webpack-plugin` publishes it, running the user's own terser since webpack lists it only as a devDependency. Neither needs an option to say which, and the printer itself never loads terser. `createModules` builds what terser's modules exported — the node factories (`createAst`), the parser's tables (`createParseTables`), the compressor and the output stream — and each entry of `PHASES` installs one part onto them: add phases there and nowhere else. A node is a plain object without methods, made by a factory `createAst` compiles from `NODE_KINDS` with its fields; its prototype is its kind's, holding its ESTree `type`, the values ESTree fixes for the kind (`prefix`, a name's `role`, a declaration's `kind`), the kind itself, which `ast.kindOf` reads, and its kind bits. A kind's prototype sits below a frozen prototype per terser class, chained as `NODE_KIND_ANCESTRY` gives each kind's classes, and `createAst` names a predicate per class, `is<Class>` (`isLambdaNode`), a bound `isPrototypeOf` of that class's prototype: the phases ask a node what it is through these, never `instanceof`. There are no node methods: every operation terser defined per class (`optimize`, `evaluate`, `has_side_effects`, `drop_side_effect_free`, `size`, scope analysis, …) is a function on `ast` dispatching on `node.type` through a table, a type absent reading the default, and walkers, transformers and the compressor are plain objects (`createWalker`, `createTransformer`, `createCompressor`), with `ast.walkNode` and `ast.transformNode` visiting children by type. A `pure_funcs` function is still handed a call under terser's field names (`args`, `expression`, `print_to_string`) through a read-only view. The parser's ESTree is adopted as the tree (`ast.adoptEstree`, which a `parse.spidermonkey` input goes through too), and `ast.toEstree` writes the SpiderMonkey JSON `format.spidermonkey` hands back, as terser's `to_mozilla_ast` did. `toPrintTree` dispatches on `type`. `correct` wraps the methods with which terser writes a wrong program and changes only that output; `corrections.enabled` switches it off. `improve` writes less where terser's longer program provably runs the same — after compressing, a statement calling a function in place with nothing passed runs its body there — and `improvements.enabled` switches it off. The `parse` phase builds the tree from `syntax-parser.js`; `syntax-printer-estree.unittest.js` holds the adopted tree to terser's own conversion, and `PARSED_DIFFERENTLY` in `syntax-printer.unittest.js` lists where the tree it builds prints otherwise than terser's. `test/specCases/minify-corpora.spectest.js` holds the whole printer to terser's output, a refusal matching any refusal, over each corpus in its `CORPORA` list (add a new one there) under the option sets in `OPTION_SETS`, and runs each output whose test states what its input prints (terser's `expect_stdout`, swc's `expected.stdout` and `exec.rs`) in terser's sandbox. A byte difference is accepted only where switching the `correct` and `improve` phases off gives terser's bytes back, and fails where `improve` writes more than without it; what it fixes is listed in `CORRECTED` (printing right with the phase, as terser without), and an output misprinting as terser's by an option's own contract in `INHERITED`, each with the reason — an entry that stops matching fails until retired. Where the reference instead refuses a source the spec allows, the parse error it answers with is listed in `REFUSED_BY_REFERENCE` with what makes the source legal; where webpack refuses a source the reference reads, the source is listed in `REFUSED_BY_WEBPACK` with the rule it breaks (a test262 test expecting a parse error needs no entry); where it reads or prints one differently, the case is listed in `REFERENCE_MISPRINTS` with what it gets wrong — a listed one webpack must still run correctly, and one the reference stops differing on fails until retired. Each output is also sized against swc's recorded one, a fixture's `output.js` or, for one of terser's cases, what swc's port of it records (gzip decides, raw breaks a tie): one bigger fails unless `test/helpers/swcSmaller.js` lists it under what swc does that webpack does not yet, and a listed one no longer bigger fails until retired. Under the default minimizer's options each source of every corpus but test262 is also minified by `oxc-minify`, held the same way to `test/helpers/oxcSmaller.js`; an oxc output that misprints is no lead. `JS_MINIFY_REPORT=<file>` tallies where webpack's is worse, the same and better. terser's corpus submodule is pinned to the `terser` devDependency — bump both together, and regenerate `data.js`.
42
-
- Printing and mangling work on ESTree, not on terser's nodes: `toPrintTree` (the `printTree` phase) converts the compressed tree to ESTree carrying what the printer reads (tokens for comments and source maps, quotes, raw numbers), its names as written, releasing terser's tree as it reads when nothing hands it back. It is a temporary bridge, removed once the compressor runs on ESTree. The `estreeMangle` phase mangles that tree as terser's mangler did: `analyzeManglingScopes` resolves its scopes, `computeEstreeCharFrequency` orders the identifiers, `mangleManglingScopes` names the definitions and `renameMangledEstree` renames them, `#private` names and properties in one walk; under `format.ast` or `format.spidermonkey` `minify` writes the names chosen back onto terser's tree it hands back. `printEstree` (the `estreePrint` phase) dispatches on `node.type` through three tables — `codegen` (the text), `needsParens` and `sourceMapping` — and asks about a parent through the `kindOf` predicates, never `instanceof`; the stream (`MinifiedOutput`) reads comments through `NodeAccess`. Everything that prints goes through it: `minify`, the mangler's character frequency and the compressor's `printToString`.
41
+
- `syntax-printer.js` — webpack's JavaScript minifier, terser's design ported to write byte for byte what terser writes; `jsMinify.js` is the `minify` the default minimizer dispatches JS to under `experiments.futureDefaults`, and goes through it alone; without that flag the minimizer dispatches to `terserMinify` as `minimizer-webpack-plugin` publishes it, running the user's own terser since webpack lists it only as a devDependency. Neither needs an option to say which, and the printer itself never loads terser. `createModules` builds what terser's modules exported — the node factories (`createAst`), the parser's tables (`createParseTables`), the compressor and the output stream — and each entry of `PHASES` installs one part onto them: add phases there and nowhere else. A node is a plain object without methods, made by a factory `createAst` compiles from `NODE_KINDS` with its fields; its prototype is its kind's, holding its ESTree `type`, the values ESTree fixes for the kind (`prefix`, a name's `role`, a declaration's `kind`), the kind itself, which `ast.kindOf` reads, and its kind bits. A kind's prototype sits below a frozen prototype per terser class, chained as `NODE_KIND_ANCESTRY` gives each kind's classes, and `createAst` names a predicate per class, `is<Class>` (`isLambdaNode`), a bound `isPrototypeOf` of that class's prototype: the phases ask a node what it is through these, never `instanceof`. There are no node methods: every operation terser defined per class (`optimize`, `evaluate`, `has_side_effects`, `drop_side_effect_free`, `size`, scope analysis, …) is a function on `ast` dispatching on `node.type` through a table, a type absent reading the default, and walkers, transformers and the compressor are plain objects (`createWalker`, `createTransformer`, `createCompressor`), with `ast.walkNode` and `ast.transformNode` visiting children by type. A `pure_funcs` function is still handed a call under terser's field names (`args`, `expression`, `print_to_string`) through a read-only view. The parser's ESTree is adopted as the tree (`ast.adoptEstree`, which a `parse.spidermonkey` input goes through too), and `ast.toEstree` writes the SpiderMonkey JSON `format.spidermonkey` hands back, as terser's `to_mozilla_ast` did. `correct` wraps the methods with which terser writes a wrong program and changes only that output; `corrections.enabled` switches it off. `improve` writes less where terser's longer program provably runs the same — after compressing, a statement calling a function in place with nothing passed runs its body there — and `improvements.enabled` switches it off. The `parse` phase builds the tree from `syntax-parser.js`; `syntax-printer-estree.unittest.js` holds the adopted tree to terser's own conversion, and `PARSED_DIFFERENTLY` in `syntax-printer.unittest.js` lists where the tree it builds prints otherwise than terser's. `test/specCases/minify-corpora.spectest.js` holds the whole printer to terser's output, a refusal matching any refusal, over each corpus in its `CORPORA` list (add a new one there) under the option sets in `OPTION_SETS`, and runs each output whose test states what its input prints (terser's `expect_stdout`, swc's `expected.stdout` and `exec.rs`) in terser's sandbox. A byte difference is accepted only where switching the `correct` and `improve` phases off gives terser's bytes back, and fails where `improve` writes more than without it; what it fixes is listed in `CORRECTED` (printing right with the phase, as terser without), and an output misprinting as terser's by an option's own contract in `INHERITED`, each with the reason — an entry that stops matching fails until retired. Where the reference instead refuses a source the spec allows, the parse error it answers with is listed in `REFUSED_BY_REFERENCE` with what makes the source legal; where webpack refuses a source the reference reads, the source is listed in `REFUSED_BY_WEBPACK` with the rule it breaks (a test262 test expecting a parse error needs no entry); where it reads or prints one differently, the case is listed in `REFERENCE_MISPRINTS` with what it gets wrong — a listed one webpack must still run correctly, and one the reference stops differing on fails until retired. Each output is also sized against swc's recorded one, a fixture's `output.js` or, for one of terser's cases, what swc's port of it records (gzip decides, raw breaks a tie): one bigger fails unless `test/helpers/swcSmaller.js` lists it under what swc does that webpack does not yet, and a listed one no longer bigger fails until retired. Under the default minimizer's options each source of every corpus but test262 is also minified by `oxc-minify`, held the same way to `test/helpers/oxcSmaller.js`; an oxc output that misprints is no lead. `JS_MINIFY_REPORT=<file>` tallies where webpack's is worse, the same and better. terser's corpus submodule is pinned to the `terser` devDependency — bump both together, and regenerate `data.js`.
42
+
- Printing and mangling read the compressed tree as it is held, by its ESTree types: no conversion step stands between the compressor and the printer, so a tree a caller passes in or `format.ast` hands back is printed and mangled as it is. Where the compressor holds a shape of its own the printer reads it directly — a template's `segments`, two side by side printing as one text; an import's `imported_name` and `imported_names`, an export's `exported_definition`, `exported_value` and `exported_names`, attributes as the object holding them; `import()`'s `args`; a key's or a property read's name as a symbol node; a literal's `role` for a regular expression or a bigint's digits — and a name prints as its `definition` names it (`mangled_name`, else the definition's own name), terser's or the mangler's alike, never renamed in place. Where nobody keeps the tree, `analyzeManglingScopes` and `printProgram` drop what only the compressor read (`COMPRESSOR_ONLY_FIELDS`) off each node they read; every field written is one its kind's factory made. The `estreeMangle` phase mangles that tree as terser's mangler did: `analyzeManglingScopes` resolves its scopes, writing each name's `definition`, `computeEstreeCharFrequency` orders the identifiers, `mangleManglingScopes` gives the definitions their `mangled_name` and `renameMangledEstree` renames `#private` names and properties in one walk, skipped where there are neither. `printEstree` (the `estreePrint` phase) dispatches on `node.type` through three tables — `codegen` (the text), `needsParens` and `sourceMapping` — and asks about a parent through the `kindOf` predicates, never `instanceof`; the stream (`MinifiedOutput`) reads comments through `NodeAccess`. Everything that prints goes through it: `minify`, the mangler's character frequency and the compressor's `printToString`.
43
43
-`yarn test:minify-corpora` — webpack's JS minifier vs the published one it replaces, byte for byte (a refusal matching any refusal), over every JS corpus: terser's own `test/compress` and `test/input`, test262, swc's minifier tests and oxc's; where a test states what its input prints, the output is also run and must print it. Each output must also be no bigger than swc's recorded one unless `SWC_SMALLER` lists why, and every output outside test262 no bigger than `oxc-minify`'s unless `OXC_SMALLER` does; `JS_MINIFY_REPORT=<file>` tallies worse, the same and better.
0 commit comments