[nstepien]

Summary

First slice split out of #68 so it can be reviewed on its own: the static-resolution and scoping semantics of parseFile, with none of the import/export machinery.

Only const bindings have a static value. let/var bindings, parameters, and destructured bindings are still recorded so they shadow outer bindings and imports (including var hoisting to the function scope), but a template using one is skipped with UNRESOLVED_INTERPOLATION. A css template assigned to a let/var is still extracted. Only references to it need a const. parseFile records the initializer of each const, and resolveValue evaluates it on demand, like an interpolation: a literal, signed numbers included (const offset = -5), or another binding that resolves (const accent = brand), class names and imports included. An imported binding is resolved in the module that declares it, so an exported alias resolves for its importers too. The values are cached for the transform, unknown ones included, and a binding is cached as unknown while it is resolved, so a cycle stays unknown. Resolution is static, so a template or a const may reference a const declared later in the file (a TDZ error at runtime). The plugin keeps resolving it on purpose, but the README does not document it, so users do not rely on it. Re-exported imports (export { x } of an import, and export … from) are still not followed.

Resolving let/var values would require reassignment tracking and, for var, position and control-flow analysis to avoid inlining a value the runtime never had (hoisted callees, conditional initialization, break label, Annex B catch). Static style tokens are idiomatically const anyway.

Tag shadowing. A local binding named like the tag means the template is not ecij's css and is left alone. Templates are collected during the visit and decided once every scope is populated, so bindings declared after the template count too (let/const/class are hoisted to their block, var/functions to their function). The tag is recognized through its import binding (cssTagNames), so import { css as styled } from 'ecij' works as a by-product.

Scopes.

• Function bodies are scopes of their own: parameter defaults cannot see the body's declarations, and body vars hoist into the body rather than next to the parameters
• Loop and catch bodies are nested in the scope of the loop head or the catch parameter instead of sharing it, so a body-level declaration cannot leak into the loop head
• The switch scope is entered with the first case, so the discriminant is evaluated in the enclosing scope
• The var declarator kind is tracked as a stack: a declarator following a sibling whose initializer contains nested declarations, like a function body, lost its kind, so a var was bound to the block (and a const would no longer resolve)
• A template's interpolations are resolved in the scope where the template appears (previously a var-declared template used the function scope, so a block-scoped binding shadowing an outer one resolved to the outer value)

Docs: the README gains a "Static resolution" section, with an example of the supported interpolations, and AGENTS.md's transform description matches. AGENTS.md also records why the const cache only lives for one transform.

Behavior changes vs main

• let/var bindings with a literal initializer no longer resolve and warn instead
• const bindings of signed numbers now resolve
• A const bound to another binding that resolves, local or imported, now resolves too, also for the modules importing it
• A binding exported under several names now resolves under each of them
• Templates whose tag is shadowed by a local binding are no longer extracted
• Aliased tag imports are now supported

Test plan

• variable scoping and advanced scoping snapshots updated for the const-only rule (§7 var, §11 for-head let, and §23 var in a block now warn). New advanced sections 32–36: var declarator kind stack, let not resolved, parameter defaults vs. body const/var, and var-declared templates resolving where they appear
• The barrel test re-exports scoping.input.ts, so it now records that fixture's var warning
• New tag-shadow-hoisting fixture and test: later const/var/function/class, self-reference, enclosing-scope declaration, nested-block negative control, and module level. Only the two unshadowed templates are extracted
• literal-interpolation gains a const bound to a signed number
• New const-alias fixture and test: aliases of literals and class names, an alias of a shadowing binding, a chain declared after its use, an alias of an import, and exported aliases of a literal, a class name, and an import resolve. Aliases of a let and a cycle warn
• Vite builds of scratch projects: a const cycle across two modules and a re-export cycle terminate unresolved, a chain of aliases across three modules resolves with the stylesheets in dependency order, modules interpolating each other's aliased class names build, and a binding exported under two names resolves under both
• node --run test (locally and with CI=true against dist/), lint, typecheck, format:check, and build pass. src/index.ts statement coverage is 99.6%, and its one uncovered line (TypeScript parameter properties) is uncovered on main too

Relationship to #68

The code here started out textually identical to the corresponding regions of #68. Merging main into it (IIFE class names, hook filters, cycle handling, and the dev server updates) and the review simplifications since then mean they no longer match, so merging main back into #68 afterwards will need conflict resolution in these regions too.

Candidate next slices:

• Raw TypeScript handling (enum/namespace/import =, moduleType-aware parsing)
• Prologue-safe import injection (Full import/export handling, query variant modules, and raw TypeScript #68's moduleSideEffects is no longer needed: main keeps such modules alive with IIFE class names)
• The rest of the import/export resolution core: re-exports, and default and namespace imports and exports
• Dev-server resolution and module identity for query variants

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: d2272a2d-4d92-4961-a994-1425942c307c

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}