yuku-analyzer 0.5.48 → 0.6.2

package/README.md

@@ -37,7 +37,7 @@ console.log(def.symbol.has(SymbolFlags.Const)); // true
 
 ## How it works
 
-Nothing semantic is reimplemented in JavaScript. The binder, scope tree, reference resolution, and module records are computed by the same well-tested native analyzer that powers the rest of Yuku, then shipped to JavaScript as one compact buffer that the JS side only decodes, through lazy zero-copy views. That handoff is usually where native tooling stalls: either every query pays an FFI round trip, or the semantics get a hand-written JS twin that slowly drifts. Here there is one implementation and one crossing, so it cannot drift, and the corner cases arrive already correct: catch-clause scope sharing, named function expression scopes, `var` hoist targets, TS declaration merging, value space versus type space, and write detection through destructuring patterns.
+Nothing semantic is reimplemented in JavaScript. The binder, scope tree, reference resolution, and module records are computed by the same well-tested native analyzer that powers the rest of Yuku, then shipped to JavaScript as one compact buffer that the JS side only decodes, through lazy zero-copy views. That handoff is usually where native tooling stalls: either every query pays an FFI round trip, or the semantics get a hand-written JS twin that slowly drifts. Here there is one implementation and one crossing, so it cannot drift, and the corner cases arrive already correct: catch-clause scope sharing, named function expression scopes, `var` hoist targets, TS declaration merging, space-aware resolution (a `const T` never captures a type-position `T` away from an outer `type T`), and write detection through destructuring patterns.
 
 ## What one `addFile` gives you
 
@@ -49,8 +49,9 @@ module.scopes               // every lexical scope, as a tree
 module.symbols              // every declared binding
 module.references           // every identifier use, resolved to its symbol
 module.unresolvedReferences // free names and globals
-module.imports              // spec-true import records
+module.imports              // import records, dynamic import() and require() included
 module.exports              // spec-true export records
+module.moduleFlags          // CommonJS classification signals
 module.diagnostics          // syntax + semantic errors
 ```
 
@@ -61,9 +62,12 @@ module.symbolOf(node)    // the symbol a node declares or references
 module.referenceOf(node) // the reference recorded for an identifier
 module.scopeOf(node)     // the innermost scope containing the node
 module.parentOf(node)    // the node that structurally contains it, or null
-module.resolve("name")   // scope-chain lookup, like the engine does at runtime
+module.resolve("name")             // scope-chain lookup, like the engine at runtime
+module.resolve("T", scope, "type") // or in another declaration space
 ```
 
+Every reference carries the declaration space its position resolves in (`ref.space`: `"value"`, `"type"`, `"namespace"`, `"typeof"`, or `"any"`), and resolution is space-aware the way TypeScript's is: an inner `const T` does not capture a type annotation's `T` away from an outer `type T`.
+
 Node identity is exact: the node you reach by walking `module.ast` and the node a semantic query returns are the same JavaScript object, so `===` always works.
 
 ## Editing the AST
@@ -151,7 +155,7 @@ const analyzer = new Analyzer({
 
 ## Performance
 
-Analysis runs in the native parser pass, so full semantics cost roughly half of parsing time on top of the parse itself. Validated against 55,000+ real-world files.
+Analysis runs in the native parser pass, so full semantics cost roughly half of parsing time on top of the parse itself. Validated against every file in the [parser test corpus](https://yuku.fyi/testing/).
 
 Concretely, on an Apple M-series machine: parsing plus complete semantic analysis of a typical source file lands well under a millisecond, walking sustains tens of millions of nodes per second, and linking a 2,000-module graph takes about a millisecond.
 

package/decode.js

@@ -204,8 +204,11 @@ _ck("JSXText", []);
 _ck("JSXSpreadChild", ["expression"]);
 _ck("Hashbang", []);
 const SCOPE_KINDS = ["global", "module", "function", "block", "class", "staticBlock", "expressionName", "tsModule"];
-const NAME_KINDS = ["named", "star", "none", "equals", "global"];
 const IMPORT_PHASES = ["source", "defer"];
+const IMPORT_KINDS = ["named", "namespace", "sideEffect", "importEquals", "dynamic", "require"];
+const EXPORT_KINDS = ["named", "reExport", "namespace", "star", "equals", "global"];
+const REFERENCE_SPACES = ["value", "type", "namespace", "typeof", "any"];
+const REFERENCE_TYPE_POSITION = [false, true, true, true, false];
 const SymbolFlags = Object.freeze({
   FunctionScopedVariable: 1 << 0,
   BlockScopedVariable: 1 << 1,
@@ -230,6 +233,7 @@ const SymbolFlags = Object.freeze({
   Import: 6144,
   ValueSpace: 127,
   TypeSpace: 952,
+  NamespaceSpace: 1136,
 });
 const CHILD_SLOTS = [
   [2, 2],
@@ -1265,7 +1269,7 @@ function decode(buffer, source) {
     const scopeCount = _u32[o], symbolCount = _u32[o + 1],
           referenceCount = _u32[o + 2], declNodeCount = _u32[o + 3],
           importCount = _u32[o + 4], exportCount = _u32[o + 5],
-          nodeScopeCount = _u32[o + 6];
+          nodeScopeCount = _u32[o + 6], moduleFlags = _u32[o + 7];
     o += 8;
     const scopes = _u32.subarray(o, o + scopeCount * 4);
     o += scopeCount * 4;
@@ -1311,16 +1315,17 @@ function decode(buffer, source) {
         scopeId: (i) => references[i * 6 + 2],
         node: (i) => node(references[i * 6 + 3]),
         nodeIndex: (i) => references[i * 6 + 3],
-        kind: (i) => IMPORT_EXPORT_KINDS[(references[i * 6 + 4] >> 0) & 1],
-        isWrite: (i) => ((references[i * 6 + 4] >> 1) & 1) !== 0,
+        space: (i) => REFERENCE_SPACES[(references[i * 6 + 4] >> 1) & 7],
+        inTypePosition: (i) => REFERENCE_TYPE_POSITION[(references[i * 6 + 4] >> 1) & 7],
+        isWrite: (i) => ((references[i * 6 + 4] >> 0) & 1) !== 0,
         symbolId: (i) => _id(references[i * 6 + 5]),
         start: (i) => startOf(references[i * 6 + 3]),
         end: (i) => endOf(references[i * 6 + 3]),
       },
       import: {
         count: importCount,
+        kind: (i) => IMPORT_KINDS[imports[i * 8 + 1] & 7],
         symbolId: (i) => _id(imports[i * 8 + 0]),
-        nameKind: (i) => NAME_KINDS[imports[i * 8 + 1] & 7],
         name: (i) => str(imports[i * 8 + 2], imports[i * 8 + 3]),
         specifier: (i) => str(imports[i * 8 + 4], imports[i * 8 + 5]),
         typeOnly: (i) => ((imports[i * 8 + 1] >> 3) & 1) !== 0,
@@ -1332,15 +1337,20 @@ function decode(buffer, source) {
       },
       export: {
         count: exportCount,
-        nameKind: (i) => NAME_KINDS[exports[i * 10 + 0] & 7],
-        fromKind: (i) => NAME_KINDS[(exports[i * 10 + 0] >> 3) & 7],
-        typeOnly: (i) => ((exports[i * 10 + 0] >> 6) & 1) !== 0,
+        kind: (i) => EXPORT_KINDS[exports[i * 10 + 0] & 7],
+        typeOnly: (i) => ((exports[i * 10 + 0] >> 3) & 1) !== 0,
         name: (i) => str(exports[i * 10 + 1], exports[i * 10 + 2]),
         fromName: (i) => str(exports[i * 10 + 4], exports[i * 10 + 5]),
         specifier: (i) => str(exports[i * 10 + 6], exports[i * 10 + 7]),
         symbolId: (i) => _id(exports[i * 10 + 3]),
         node: (i) => node(exports[i * 10 + 8]),
       },
+      moduleFlags: {
+        usesRequire: (moduleFlags & 1) !== 0,
+        usesModule: (moduleFlags & 2) !== 0,
+        usesExports: (moduleFlags & 4) !== 0,
+        usesImportMeta: (moduleFlags & 8) !== 0,
+      },
       nodeScope: (i) => nodeScopes[i],
     });
   }

package/index.d.ts

@@ -123,8 +123,25 @@ declare const SymbolFlags: {
   readonly ValueSpace: number;
   /** Composite: referencable from a type position (class, enum, interface, alias, type param). */
   readonly TypeSpace: number;
+  /** Composite: what a dotted type name starts from (namespace, enum). */
+  readonly NamespaceSpace: number;
 };
 
+/**
+ * The declaration space a reference position resolves in, matching
+ * TypeScript name resolution. A binding outside a reference's space
+ * does not shadow: an inner `const T` never captures a type-position
+ * `T` away from an outer `type T`, and vice versa.
+ *
+ * - `"value"`: runtime uses
+ * - `"type"`: annotations, heritage clauses, type arguments
+ * - `"namespace"`: the qualifier of a dotted type name (`ns.T`, `E.A`)
+ * - `"typeof"`: value uses inside a type (`typeof x`, `x is T` params)
+ * - `"any"`: alias positions accepting every space (`export { x }`,
+ *   `export default x`, `export = x`, `import a = x`)
+ */
+type Space = "value" | "type" | "namespace" | "typeof" | "any";
+
 /** What kind of construct created a {@link Scope}. */
 type ScopeKind =
   | "global"
@@ -191,6 +208,12 @@ interface Symbol {
   has(mask: number): boolean;
   /** True when every flag in `mask` is set. */
   hasAll(mask: number): boolean;
+  /**
+   * True when a reference resolving in `space` may bind to this
+   * symbol, the acceptance rule of name resolution. Import bindings
+   * alias symbols of unknowable space and are visible in every space.
+   */
+  visibleIn(space: Space): boolean;
   /**
    * The defining site of this symbol, following import/re-export chains
    * across modules. Shorthand for {@link Analyzer.definitionOf}.
@@ -209,8 +232,14 @@ interface Reference {
   readonly scope: Scope;
   /** The identifier node, the same object as in the walked AST. */
   readonly node: Identifier | JSXIdentifier;
-  /** `"value"` for runtime uses, `"type"` for TS type-position uses. */
-  readonly kind: "value" | "type";
+  /** The declaration {@link Space} this position resolves in. */
+  readonly space: Space;
+  /**
+   * True when the position sits inside a type-only subtree (`"type"`,
+   * `"namespace"`, `"typeof"` spaces): erased at compile time, so a
+   * rename tool can change a value without touching a same-named type.
+   */
+  readonly inTypePosition: boolean;
   /**
    * True when this reference (re)assigns its binding: assignment
    * targets, `++`/`--` operands, for-in/of iteration variables, and
@@ -218,7 +247,10 @@ interface Reference {
    * and write.
    */
   readonly isWrite: boolean;
-  /** The symbol this resolves to, or null for free/global names. */
+  /**
+   * The symbol this resolves to, or null when no binding is visible
+   * in this reference's space (globals, undeclared names).
+   */
   readonly symbol: Symbol | null;
 }
 
@@ -396,9 +428,12 @@ interface Module {
   parentOf(node: Node): Node | null;
   /**
    * Walks the scope chain from `from` (default: the root scope) to
-   * find the nearest binding of `name`.
+   * find the nearest binding of `name` visible in `space` (default:
+   * `"value"`, resolving like runtime code). A binding outside the
+   * space does not shadow, the walk keeps going. `"any"` matches by
+   * name alone.
    */
-  resolve(name: string, from?: Scope): Symbol | null;
+  resolve(name: string, from?: Scope, space?: Space): Symbol | null;
   /**
    * The free variables of a function or arrow: every binding referenced
    * inside it (nested closures included, value positions only) that is
@@ -542,6 +577,7 @@ export {
   type Reference,
   type Scope,
   type ScopeKind,
+  type Space,
   type Symbol,
   type Visitors,
   type WalkContext,

package/module.js

@@ -85,6 +85,24 @@ class Symbol {
   hasAll(mask) {
     return (this.flags & mask) === mask;
   }
+  // the acceptance rule of name resolution. import bindings alias
+  // symbols of unknowable space and are visible in every space
+  visibleIn(space) {
+    const flags = this.flags;
+    if ((flags & SymbolFlags.Import) !== 0) return true;
+    switch (space) {
+      case "value":
+      case "typeof":
+        return (flags & SymbolFlags.ValueSpace) !== 0;
+      case "type":
+        return (flags & SymbolFlags.TypeSpace) !== 0;
+      case "namespace":
+        return (flags & SymbolFlags.NamespaceSpace) !== 0;
+      case "any":
+        return true;
+    }
+    throw new TypeError(`visibleIn: unknown space "${space}"`);
+  }
   definition() {
     return this.module.analyzer.definitionOf(this);
   }
@@ -106,8 +124,11 @@ class Reference {
   get node() {
     return this.#sem.reference.node(this.id);
   }
-  get kind() {
-    return this.#sem.reference.kind(this.id);
+  get space() {
+    return this.#sem.reference.space(this.id);
+  }
+  get inTypePosition() {
+    return this.#sem.reference.inTypePosition(this.id);
   }
   get isWrite() {
     return this.#sem.reference.isWrite(this.id);
@@ -126,21 +147,28 @@ class Import {
     this.#sem = sem;
     this._resolved = null;
   }
-  get #nameKind() {
-    return this.#sem.import.nameKind(this.id);
+  get kind() {
+    return this.#sem.import.kind(this.id);
   }
   get local() {
     const s = this.#sem.import.symbolId(this.id);
     return s === null ? null : this.module.symbols[s];
   }
   get name() {
-    return this.#nameKind === "named" ? this.#sem.import.name(this.id) : null;
+    return this.kind === "named" ? this.#sem.import.name(this.id) : null;
   }
   get isNamespace() {
-    return this.#nameKind === "star" && this.local !== null;
+    const kind = this.kind;
+    return kind === "namespace" || kind === "importEquals";
   }
   get isSideEffect() {
-    return this.#nameKind === "none";
+    return this.kind === "sideEffect";
+  }
+  get isDynamic() {
+    return this.kind === "dynamic";
+  }
+  get isRequire() {
+    return this.kind === "require";
   }
   get typeOnly() {
     return this.#sem.import.typeOnly(this.id);
@@ -168,23 +196,23 @@ class Export {
     this.#sem = sem;
     this._resolved = null;
   }
-  get #nameKind() {
-    return this.#sem.export.nameKind(this.id);
-  }
-  get #fromKind() {
-    return this.#sem.export.fromKind(this.id);
+  get kind() {
+    return this.#sem.export.kind(this.id);
   }
   get name() {
-    return this.#nameKind === "named" ? this.#sem.export.name(this.id) : null;
+    const kind = this.kind;
+    return kind === "named" || kind === "reExport" || kind === "namespace"
+      ? this.#sem.export.name(this.id)
+      : null;
   }
   get isStar() {
-    return this.#nameKind === "star";
+    return this.kind === "star";
   }
   get isExportEquals() {
-    return this.#nameKind === "equals";
+    return this.kind === "equals";
   }
   get globalName() {
-    return this.#nameKind === "global" ? this.#sem.export.name(this.id) : null;
+    return this.kind === "global" ? this.#sem.export.name(this.id) : null;
   }
   get typeOnly() {
     return this.#sem.export.typeOnly(this.id);
@@ -194,13 +222,16 @@ class Export {
     return s === null ? null : this.module.symbols[s];
   }
   get specifier() {
-    return this.#fromKind === "none" ? null : this.#sem.export.specifier(this.id);
+    const kind = this.kind;
+    return kind === "reExport" || kind === "namespace" || kind === "star"
+      ? this.#sem.export.specifier(this.id)
+      : null;
   }
   get fromName() {
-    return this.#fromKind === "named" ? this.#sem.export.fromName(this.id) : null;
+    return this.kind === "reExport" ? this.#sem.export.fromName(this.id) : null;
   }
   get isNamespaceReexport() {
-    return this.#fromKind === "star";
+    return this.kind === "namespace";
   }
   get node() {
     return this.#sem.export.node(this.id);
@@ -272,6 +303,9 @@ export class Module {
   get exports() {
     return (this.#exports ??= this.#rows(Export, this.#sem.export.count));
   }
+  get moduleFlags() {
+    return this.#sem.moduleFlags;
+  }
   get unresolvedReferences() {
     return (this.#unresolved ??= this.references.filter((r) => r.symbol === null));
   }
@@ -316,10 +350,13 @@ export class Module {
     return parent < 0 ? null : this.#r.nodeOf(parent);
   }
 
-  resolve(name, from = this.rootScope) {
+  // the space filters what the name can see, exactly like reference
+  // resolution: a binding outside the space does not shadow, the walk
+  // keeps going. "any" matches by name alone
+  resolve(name, from = this.rootScope, space = "value") {
     for (let s = from; s; s = s.parent) {
       const found = s.find(name);
-      if (found) return found;
+      if (found && found.visibleIn(space)) return found;
     }
     return null;
   }
@@ -355,7 +392,7 @@ export class Module {
     const captures = new Map();
     for (let i = 0; i < reference.count; i++) {
       const symbolId = reference.symbolId(i);
-      if (symbolId === null || reference.kind(i) === "type") continue;
+      if (symbolId === null || reference.inTypePosition(i)) continue;
       if (reference.start(i) < start || reference.end(i) > end) continue;
       let inside = false;
       for (let s = symbol.scopeId(symbolId); s !== null; s = scope.parentId(s)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuku-analyzer",
-  "version": "0.5.48",
+  "version": "0.6.2",
   "description": "Full JavaScript and TypeScript semantic analysis: scopes, symbols, resolved references, closures, and cross-file module linking, computed natively in Zig and queried as plain JavaScript objects",
   "license": "MIT",
   "repository": {
@@ -21,17 +21,17 @@
     "decode.js"
   ],
   "optionalDependencies": {
-    "@yuku-analyzer/binding-linux-x64-gnu": "0.5.48",
-    "@yuku-analyzer/binding-linux-arm64-gnu": "0.5.48",
-    "@yuku-analyzer/binding-linux-arm-gnu": "0.5.48",
-    "@yuku-analyzer/binding-linux-x64-musl": "0.5.48",
-    "@yuku-analyzer/binding-linux-arm64-musl": "0.5.48",
-    "@yuku-analyzer/binding-linux-arm-musl": "0.5.48",
-    "@yuku-analyzer/binding-darwin-x64": "0.5.48",
-    "@yuku-analyzer/binding-darwin-arm64": "0.5.48",
-    "@yuku-analyzer/binding-win32-x64": "0.5.48",
-    "@yuku-analyzer/binding-win32-arm64": "0.5.48",
-    "@yuku-analyzer/binding-freebsd-x64": "0.5.48"
+    "@yuku-analyzer/binding-linux-x64-gnu": "0.6.2",
+    "@yuku-analyzer/binding-linux-arm64-gnu": "0.6.2",
+    "@yuku-analyzer/binding-linux-arm-gnu": "0.6.2",
+    "@yuku-analyzer/binding-linux-x64-musl": "0.6.2",
+    "@yuku-analyzer/binding-linux-arm64-musl": "0.6.2",
+    "@yuku-analyzer/binding-linux-arm-musl": "0.6.2",
+    "@yuku-analyzer/binding-darwin-x64": "0.6.2",
+    "@yuku-analyzer/binding-darwin-arm64": "0.6.2",
+    "@yuku-analyzer/binding-win32-x64": "0.6.2",
+    "@yuku-analyzer/binding-win32-arm64": "0.6.2",
+    "@yuku-analyzer/binding-freebsd-x64": "0.6.2"
   },
   "keywords": [
     "analyzer",