Crate skif_js_syntax

Expand description

The oxc boundary of skif: one JavaScript or TypeScript file in, skif-owned facts out.

parse_module returns a ModuleInfo (imports, exports, in-file references, removal ranges) and extract_config_object statically evaluates the object a tool config file exports. extract_config returns an ExtractedConfig: that value and the evaluated arguments of the calls the evaluator cannot follow that the file exports, returns from its config function or merges, following imports when given a ModuleLoader. No oxc type appears in the public API, every public type is Send + Sync, and no oxc value outlives the call that parsed it: each thread parses into one arena it resets before every parse.

Supported inputs are .js .mjs .cjs .jsx .ts .mts .cts .tsx and declaration files (is_declaration_file), plus the <script> blocks (and Astro frontmatter), the <style> imports and the markup identifiers of .vue, .svelte and .astro files: component tags and the expressions of the template count as uses of the imports they name, unless a template local of the same name (v-for, {#each}, an arrow parameter) shadows the import. .mdx files yield the facts of their top-level import and export statements, and the components their markup names count as uses. .tsrx files yield their imports only, since their templates are no JavaScript, and .marko files their imports and the imports of their style blocks. Stylesheets go through parse_stylesheet. Other extensions yield SyntaxError::Unsupported. registered_components reads the components a components.d.ts generated by unplugin-vue-components registers.

parse_cached parses through a ModuleCache the host supplies, keyed by a ModuleKey over everything a parse depends on, so a long-lived or persisting host parses only the files that changed (ADR 0029).

Structs§

CachedModule: One cached parse result. Its fields are private: a host stores and serializes it without depending on the shape of ModuleInfo.
ConfigComments: The comments of a configuration file’s literals, from extract_config_comments.
ElementComment: The comment written next to one element of an array literal: on the lines directly above it, or after it on the line where it ends.
Export: One export of a module.
ExtractedConfig: What a config file exports, with the arguments of the calls it is made of that cannot be followed.
Import: A module reference.
ImportedCall: A call, or a tagged template, of a function a module exports; see extract_imported_calls.
ImportedName: One binding brought in by an Import.
Member: A member of an enum or TypeScript namespace.
MemoryModuleCache: An in-process ModuleCache for long-lived hosts (watch mode, the language server, the MCP server).
ModuleInfo: Everything skif needs to know about one source file.
ModuleKey: The key of one parse result: a 128-bit SipHash-1-3 of the schema, the crate version, the parser, the parse options, the file name and the text. The directory is not part of it, so identical files share an entry and a moved checkout keeps its cache.
ParseCoalescer: Parses each key once while several threads ask for it: a lookup of a key another thread is parsing waits for that parse and is given its outcome instead of parsing the file again (ADR 0029).
ParseIssue: A syntax problem reported by the parser. The analysis of the file continues on the parser’s recovered program.
ParseOptions: Options for crate::parse_module.
PropertyComment: The comment written next to a property of an object literal: on the lines directly above it, after it on the line where it ends, or, when its value is an array literal, after the opening bracket on the bracket’s line.
RegisteredComponent: A component registered globally by a generated declaration file: AppButton: typeof import('./src/components/AppButton.vue')['default'].
Removal: A byte range to delete to fix an unused export.

Enums§

ConfigValue: A statically known value from a config file.
ExportKind: What an export is.
ImportKind: How a module is pulled in.
ImportedKind: Which export of the target module a binding refers to.
MockCall: A test-runner call that names a module, recorded on an ImportKind::Mock import. It serializes as the call is written ("vi.mock").
PathSegment: One step of the path from an outermost object or array literal to an array literal.
Registration: How a class is registered as a custom element (ADR 0020).
RemovalKind: What a removal edit deletes.
SyntaxError: Why a file could not be turned into a crate::ModuleInfo.

Constants§

CACHE_SCHEMA: The version of the parse output. Raise it whenever ModuleInfo or what the parsers put in it changes, so a cache written by an older build at the same crate version is not trusted; the test the_cache_schema_matches_the_parse_output fails until CACHE_SCHEMA_DIGEST is updated with it.
CACHE_SCHEMA_DIGEST: The digest of the serialized parse results of a fixed probe corpus at CACHE_SCHEMA. It is a test’s guard, not part of any key: when the parse output changes, the test reports the new digest and both constants move.
DECLARATION_SUFFIXES: The suffixes of TypeScript declaration files: .d.ts, .d.mts and .d.cts.
FILE_DIR: What the directory of the calling file reads as in the cwd option of an ImportedCall that the file’s own location computes (__dirname, import.meta.dirname, path.join(__dirname, 'fixtures')), followed by / and the path relative to the file’s directory ($__skif_file_dir__/./fixtures). command_in_call_dir changes to it, and place_file_dir puts the file’s directory in its place.
OWN_SPREAD: Like UNKNOWN_SPREAD, for an unknown value the module computes itself: a spread or merge of a call of, or a reference to, a function or constant it defines, or a binding of a function being evaluated (build: { ...makeLib() }). A value imported from another module records these as UNKNOWN_SPREAD too.
TEMPLATE_SUBSTITUTION: What a substitution of a tagged template reads as in ImportedCall::template.
UNKNOWN_SPREAD: The key under which an object records an unknown spread, or an unknown argument of a merge, of a value the module takes from elsewhere: an imported base config, a merge of imported ones, a global. It may add or replace any key.

Traits§

ModuleCache: A store of parse results the host owns and gives the analysis.
ModuleLoader: Finds the modules a config file imports, so their values can be evaluated statically too.

Functions§

cache_version: The version a persisted cache records, <crate version>+<CACHE_SCHEMA>: a store written under another version is discarded as a whole.
camelize: Vue’s camelize: each - before a word character is dropped and the character upper-cased (my-button as myButton).
capitalize: Vue’s capitalize: the first character upper-cased (myButton as MyButton).
coalesce_ranges: Merges overlapping and touching byte ranges into sorted, disjoint ones.
command_in_call_dir: command as a call whose options object is options runs it. A cwd option the file’s own location computes (FILE_DIR) runs it in that directory, so the command line first changes to it (cd $__skif_file_dir__/. && …). Any other cwd runs it in a directory the script parser cannot place (a literal path is relative to the process, which the parser does not know), so the command line first changes to a directory a substitution names (cd $__skif__ && …): a package manager’s script run there is another package’s, as with bun --cwd.
command_line_call: The command of a (command line, options) call such as execSync('tsc -b', { cwd }), in the directory its cwd option names (see command_in_call_dir); None unless the command line is a string.
extract_array_comments: The comments next to the elements of the array literals of source, a JavaScript or TypeScript file whose extension (in path) selects the dialect. Paths start at each outermost object or array literal, so the object a config file exports, directly or through a constant or a call such as defineConfig({ ... }), is the root. A property or element whose value is the name of a top-level const bound to an object or array literal is followed into that literal, so const deps = [...]; export default { ignoreDependencies: deps } puts the comments of deps under ignoreDependencies (they are also reported under deps as a root of its own). A spread is not followed. A comment that is a tool directive (// eslint-disable-next-line, // @ts-expect-error) is left out.
extract_command_calls: The calls of extract_imported_calls for functions that run a command (execa, nano-spawn), whose cwd option is read as the directory the command runs in (see ImportedCall::arguments).
extract_config: Statically evaluates what source exports, as extract_config_object does, keeping the arguments of the calls it is made of that cannot be followed (ExtractedConfig::call_arguments).
extract_config_comments: The comments of source that extract_array_comments reads, with an ElementComment under a heading for every element whose only explanation is the comment above an earlier element of its array, and a PropertyComment for every property with a static key that has a comment. Properties are walked as elements are: a property whose value names a top-level const literal is followed into it.
extract_config_object: Statically evaluates what source exports: export default …, module.exports = … or export = ….
extract_config_object_with: The exported value extract_config finds with loader, following the imports it finds.
extract_constructor_options: Statically evaluates the option key of every new constructor({ … }) in source, however the constructor was imported (new NodejsFunction(…), new lambda_nodejs.NodejsFunction(…)). Path computations are relative to the directory of path. Returns nothing when the file does not parse.
extract_imported_calls: Every call and tagged template in source whose function is imported from one of modules (import, import * as, or a top-level require, plain or destructured), with its arguments statically evaluated as in extract_config_object. globals names functions available without an import, as (name, module) pairs (the $ of a zx script); a name written Bun.* stands for the module object itself, so Bun.$`…` and Bun.build(…) call the exports $ and build of the module. Shadowed names are not tracked. Returns nothing when the file does not parse.
extract_method_calls: Statically evaluates the arguments of every call of a method named method in source, whatever object it is called on (eleventyConfig.addPassthroughCopy("img")), in source order: one list of arguments per call. Arguments are evaluated as in extract_config_object, so a top-level constant is known and a local of the enclosing function is not. Returns nothing when the file does not parse.
extract_property_calls: Statically calls every function that is the property key of an object literal in source, a method (configureWebpack(config) { … }) or a function or arrow value, with argument as its first parameter, in source order. Each result is the value the function returns or, when its body finishes without a return, what it leaves its first parameter as: a function that changes the object it is given (config.entry = { … }) yields the changed object. Calls are evaluated as in extract_config_object; a property that is not a function is left out. Returns nothing when the file does not parse.
extract_property_values: Statically evaluates the value of every property named key of every object literal in source, however deeply nested and wherever it appears (handler: "src/api.handler" inside a function body), in source order. Values are evaluated as in extract_config_object, against the top-level bindings, with paths relative to the directory of path; a name a function, block, loop or catch around the property declares is unknown, whatever top-level binding it shadows. Methods are left out. Returns nothing when the file does not parse.
file_call_options: The options object of a (file, [arguments], options) call such as spawn('eslint', ['.'], { cwd }): the argument after the arguments array, or the second argument when that is no array.
is_declaration_file: Whether path, a path or a file name, names a TypeScript declaration file (.d.ts, .d.mts, .d.cts).
is_native_tag: Whether tag is an element of HTML, SVG or MathML, or the component and slot of Vue’s compiler, as written: Vue never resolves such a tag to a registered component. The match is case-sensitive, as Vue’s: <Button> is a component.
is_source_query: Whether a query (?raw, raw&inline, with or without its ?) makes Vite load a file’s text instead of the module, by Vite’s own test: a raw parameter with no value. ?url is not one: it names the file to load it some other way (a worklet, a worker), so the file still counts as used.
is_stylesheet: Whether path has a stylesheet extension.
literal_command: The command line of a (file, [arguments]) call such as spawn('eslint', ['.']): the file and its literal arguments, a computed argument left out. None when the file or a literal argument is not a plain word, because dropping it would change what the command means.
parse_cached: Parses source, the text of path, with options, through cache: a stored result is returned as it is, and a fresh parse is stored before it is returned. Stylesheets go to parse_stylesheet and everything else to crate::parse_module. Without a cache this is a plain parse.
parse_module: Parses source (the content of path) into a ModuleInfo. The extension of path selects the language.
parse_stylesheet: Scans the stylesheet source (the content of path) for the files and packages it imports. Every import has ImportKind::SideEffect. Nothing is reported for remote URLs, data: URLs, Sass built-in modules, specifiers with interpolation and Stylus globs (@import "mixins/*").
place_file_dir: command with the directory of file, the file that runs it as a /-separated path relative to the directory where the command starts, in place of FILE_DIR, single-quoted so that a shell reads it as part of one word whatever it holds (cd 'my scripts'/../sub).
registered_components: The components source, the text of a components.d.ts that unplugin-vue-components generated, registers from files of the project, in source order: each property of GlobalComponents and each global const whose type is typeof import('./…')[…], as knip reads them. A Lazy variant of a registered name (LazyAppIcon beside AppIcon) is the same component and is left out; a LazyImage registered on its own is a component of its own. Components of packages (typeof import('vant')['Button']) are left out too: the declaration file keeps importing them.
registered_name: The registered component the tag tag names, by resolved_names, or by the name after a Lazy prefix (LazyAppButton, lazy-app-button) as knip also matches it; None for a native tag (is_native_tag).
resolved_names: The names Vue looks a tag up by, in its order and without repeats: as written, camelized, and camelized and capitalised (my-button, myButton, MyButton). The compiler resolves a tag to a binding of the script this way, and the runtime (resolveAsset) to a registered component.