@xnoxs/flux-lang 3.1.1

package/src/linter.js

@@ -0,0 +1,758 @@
+'use strict';
+
+const { Lexer }  = require('./lexer');
+const { Parser } = require('./parser');
+
+// ── Flux Linter ───────────────────────────────────────────────────────────────
+// AST-level lint rules (beyond type-safety — these catch logic smells):
+//
+//   RULE 1 — unused-var      : val/var declared but never read
+//   RULE 2 — unreachable     : statements after return/throw/break/continue
+//   RULE 3 — shadow-val      : inner val/var shadows an outer binding
+//
+// Each issue has: { rule, severity ('error'|'warn'|'info'), message, hint, line, col }
+
+class LintIssue {
+  constructor(rule, severity, message, hint, loc) {
+    this.rule     = rule;
+    this.severity = severity;
+    this.message  = message;
+    this.hint     = hint || null;
+    this.line     = loc ? loc.line : null;
+    this.col      = loc ? loc.col  : null;
+  }
+}
+
+// ── Scope tracking ────────────────────────────────────────────────────────────
+// Each entry: { kind, loc, used: bool, shadowOf: entry|null }
+class LintScope {
+  constructor(parent = null, kind = 'block') {
+    this.parent  = parent;
+    this.kind    = kind;  // 'block' | 'fn' | 'class'
+    this.vars    = new Map();
+  }
+
+  define(name, kind, loc) {
+    const shadowOf = this.lookupOwn(name) || this._lookupParent(name);
+    const entry = { name, kind, loc, used: false, shadowOf };
+    this.vars.set(name, entry);
+    return entry;
+  }
+
+  lookupOwn(name) {
+    return this.vars.get(name) || null;
+  }
+
+  _lookupParent(name) {
+    let s = this.parent;
+    while (s) {
+      if (s.vars.has(name)) return s.vars.get(name);
+      s = s.parent;
+    }
+    return null;
+  }
+
+  lookup(name) {
+    return this.lookupOwn(name) || this._lookupParent(name);
+  }
+
+  markUsed(name) {
+    const entry = this.lookup(name);
+    if (entry) entry.used = true;
+  }
+
+  // Collect all entries defined in THIS scope only
+  ownEntries() {
+    return [...this.vars.values()];
+  }
+}
+
+// ── Names to skip for "unused" (exports, builtins, convention prefixes) ───────
+const BUILTIN_NAMES = new Set([
+  'self', 'this', 'arguments', 'exports', 'module', 'require', '__dirname',
+  '__filename', 'process', 'console', 'Math', 'JSON', 'Object', 'Array',
+  'String', 'Number', 'Boolean', 'Promise', 'Error', 'Symbol', 'Map', 'Set',
+  'WeakMap', 'WeakSet', 'Proxy', 'Reflect', 'undefined', 'null', 'true', 'false',
+  'NaN', 'Infinity', 'parseInt', 'parseFloat', 'isNaN', 'isFinite', 'setTimeout',
+  'clearTimeout', 'setInterval', 'clearInterval', 'fetch', 'globalThis',
+  // Flux stdlib names
+  'print', 'truncate', 'range', 'sum', 'first', 'last', 'zip', 'flatten',
+  'groupBy', 'unique', 'sortBy', 'chunk',
+]);
+
+function isIgnoredName(name) {
+  if (BUILTIN_NAMES.has(name)) return true;
+  if (name.startsWith('_'))    return true;  // underscore prefix = intentionally unused
+  return false;
+}
+
+// ── The Linter ────────────────────────────────────────────────────────────────
+class Linter {
+  constructor() {
+    this.issues = [];
+  }
+
+  lint(ast) {
+    this.issues = [];
+    const scope = new LintScope(null, 'module');
+    this._walkStmts(ast.body, scope, { inFn: false });
+    return this.issues;
+  }
+
+  _issue(rule, severity, message, hint, loc) {
+    this.issues.push(new LintIssue(rule, severity, message, hint, loc));
+  }
+
+  // ── Statement list walker ────────────────────────────────────────────────
+  _walkStmts(stmts, scope, ctx) {
+    if (!stmts || stmts.length === 0) return;
+
+    for (let i = 0; i < stmts.length; i++) {
+      const node = stmts[i];
+
+      // RULE 2: unreachable code after terminating statement
+      if (i > 0 && this._isTerminator(stmts[i - 1])) {
+        // Skip blank/comment nodes (they have no loc usually)
+        if (node && node.loc) {
+          this._issue(
+            'unreachable',
+            'error',
+            `Unreachable code after '${this._terminatorName(stmts[i - 1])}'`,
+            `Remove or move the unreachable statement`,
+            node.loc
+          );
+          // Report only the first unreachable per block to avoid cascade
+          break;
+        }
+      }
+
+      this._walkStmt(node, scope, ctx);
+    }
+
+    // After walking the block, check for unused vars declared in this scope
+    this._checkUnused(scope);
+  }
+
+  _isTerminator(node) {
+    if (!node) return false;
+    if (node.type === 'ReturnStmt' || node.type === 'ThrowStmt') return true;
+    if (node.type === 'BreakStmt'  || node.type === 'ContinueStmt') return true;
+    // Inline fn body ending in return
+    return false;
+  }
+
+  _terminatorName(node) {
+    const map = {
+      ReturnStmt:   'return',
+      ThrowStmt:    'throw',
+      BreakStmt:    'break',
+      ContinueStmt: 'continue',
+    };
+    return map[node.type] || 'terminator';
+  }
+
+  // ── Unused variable check ────────────────────────────────────────────────
+  _checkUnused(scope) {
+    for (const entry of scope.ownEntries()) {
+      if (entry.used)               continue;
+      if (isIgnoredName(entry.name)) continue;
+      // Exported names are considered used by the outside world
+      if (entry._exported)          continue;
+
+      this._issue(
+        'unused-var',
+        'warn',
+        `'${entry.name}' is declared but never used`,
+        `Prefix with '_' (e.g. '_${entry.name}') to silence this warning, or remove the declaration`,
+        entry.loc
+      );
+    }
+  }
+
+  // ── Statement walker ─────────────────────────────────────────────────────
+  _walkStmt(node, scope, ctx) {
+    if (!node) return;
+    switch (node.type) {
+
+      case 'VarDecl': {
+        if (node.init) this._walkExpr(node.init, scope, ctx);
+        const entry = scope.define(node.name, node.kind, node.loc);
+        // Function declarations at module top-level are implicitly "used" (callable)
+        break;
+      }
+
+      case 'DestructureDecl': {
+        if (node.init) this._walkExpr(node.init, scope, ctx);
+        if (node.patternType === 'object') {
+          for (const p of node.pattern) {
+            scope.define(p.alias || p.name, node.kind, node.loc);
+          }
+        } else {
+          for (const p of node.pattern) {
+            if (p) scope.define(p.name, node.kind, node.loc);
+          }
+        }
+        break;
+      }
+
+      case 'FnDecl': {
+        // Function name itself is used (callable), mark as used
+        if (node.name) {
+          const entry = scope.define(node.name, 'val', node.loc);
+          entry.used = true;  // fn names are callable references, treat as used
+        }
+        const inner = new LintScope(scope, 'fn');
+        for (const p of node.params) {
+          const pe = inner.define(p.name, 'val', node.loc);
+          pe.used = true;  // params: checked at call site, not by the linter
+        }
+        if (node.inline) {
+          this._walkExpr(node.body, inner, { ...ctx, inFn: true });
+        } else {
+          this._walkStmts(node.body, inner, { ...ctx, inFn: true });
+        }
+        break;
+      }
+
+      case 'ClassDecl': {
+        const ce = scope.define(node.name, 'val', node.loc);
+        ce.used = true;  // class names are constructors — external usage possible
+        const cls = new LintScope(scope, 'class');
+        for (const f of (node.fields || [])) {
+          const fe = cls.define(f.name, 'var', node.loc);
+          fe.used = true;  // fields accessed via self.x — not trackable statically
+        }
+        for (const m of (node.methods || [])) this._walkStmt(m, cls, ctx);
+        break;
+      }
+
+      case 'TypeDecl': {
+        // ADT variant constructors are used at construction & pattern-match sites
+        for (const v of node.variants) {
+          const ve = scope.define(v.name, 'val', node.loc);
+          ve.used = true;
+        }
+        break;
+      }
+
+      case 'InterfaceDecl':
+      case 'EnumDecl': {
+        const ie = scope.define(node.name, 'val', node.loc);
+        ie.used = true;
+        break;
+      }
+
+      case 'IfStmt': {
+        this._walkExpr(node.cond, scope, ctx);
+        const thenScope = new LintScope(scope, 'block');
+        this._walkStmts(node.then, thenScope, ctx);
+        for (const ei of (node.elseifs || [])) {
+          this._walkExpr(ei.cond, scope, ctx);
+          const eis = new LintScope(scope, 'block');
+          this._walkStmts(ei.body, eis, ctx);
+        }
+        if (node.else_) {
+          const elseScope = new LintScope(scope, 'block');
+          this._walkStmts(node.else_, elseScope, ctx);
+        }
+        break;
+      }
+
+      case 'ForInStmt': {
+        this._walkExpr(node.iter, scope, ctx);
+        const forScope = new LintScope(scope, 'block');
+        const loopVar  = forScope.define(node.var, 'val', node.loc);
+        loopVar.used   = true;  // loop var used in body implicitly
+        this._walkStmts(node.body, forScope, { ...ctx, inLoop: true });
+        break;
+      }
+
+      case 'WhileStmt': {
+        this._walkExpr(node.cond, scope, ctx);
+        const ws = new LintScope(scope, 'block');
+        this._walkStmts(node.body, ws, { ...ctx, inLoop: true });
+        break;
+      }
+
+      case 'DoWhileStmt': {
+        const ds = new LintScope(scope, 'block');
+        this._walkStmts(node.body, ds, { ...ctx, inLoop: true });
+        this._walkExpr(node.cond, scope, ctx);
+        break;
+      }
+
+      case 'MatchStmt': {
+        this._walkExpr(node.subject, scope, ctx);
+        for (const arm of node.arms) {
+          const armScope = new LintScope(scope, 'block');
+          if (arm.pattern && arm.pattern.type === 'VariantPat') {
+            for (const b of arm.pattern.bindings) {
+              const be = armScope.define(b, 'val', node.loc);
+              be.used = true;  // bindings used in arm body
+            }
+          }
+          if (arm.guard) this._walkExpr(arm.guard, armScope, ctx);
+          if (arm.inline) {
+            // Inline arm: single expression body
+            const expr = arm.body && arm.body[0] && arm.body[0].expr
+              ? arm.body[0].expr : arm.body[0];
+            if (expr) this._walkExpr(expr, armScope, ctx);
+          } else {
+            this._walkStmts(arm.body || [], armScope, ctx);
+          }
+        }
+        break;
+      }
+
+      case 'ReturnStmt':
+        if (node.value) this._walkExpr(node.value, scope, ctx);
+        break;
+
+      case 'ThrowStmt':
+        this._walkExpr(node.value, scope, ctx);
+        break;
+
+      case 'TryCatchStmt': {
+        const tryS = new LintScope(scope, 'block');
+        this._walkStmts(node.tryBody, tryS, ctx);
+        if (node.catchBody) {
+          const catchS = new LintScope(scope, 'block');
+          if (node.catchParam) {
+            const ce2 = catchS.define(node.catchParam, 'val', node.loc);
+            ce2.used = true;
+          }
+          this._walkStmts(node.catchBody, catchS, ctx);
+        }
+        if (node.finallyBody) {
+          const finS = new LintScope(scope, 'block');
+          this._walkStmts(node.finallyBody, finS, ctx);
+        }
+        break;
+      }
+
+      case 'ImportDecl': {
+        // Imported names: mark as used (they come from outside, their usage
+        // may be in codepaths we can't fully trace — conservative)
+        if (node.defaultName) {
+          const ie2 = scope.define(node.defaultName, 'val', node.loc);
+          ie2.used = true;
+        }
+        if (node.namespaceName) {
+          const ne = scope.define(node.namespaceName, 'val', node.loc);
+          ne.used = true;
+        }
+        for (const n of (node.names || [])) {
+          const nm = typeof n === 'string' ? n : n.alias;
+          const ie3 = scope.define(nm, 'val', node.loc);
+          ie3.used = true;
+        }
+        break;
+      }
+
+      case 'ExportDecl': {
+        // Exported declarations: mark name as used
+        const inner = node.isDefault
+          ? { type: 'ExprStmt', expr: node.decl }
+          : node.decl;
+        this._walkStmt(inner, scope, ctx);
+        // Mark the exported name as used
+        if (node.decl && node.decl.name) {
+          const ee = scope.lookup(node.decl.name);
+          if (ee) { ee.used = true; ee._exported = true; }
+        }
+        break;
+      }
+
+      case 'ExprStmt':
+        this._walkExpr(node.expr, scope, ctx);
+        break;
+
+      case 'BreakStmt':
+      case 'ContinueStmt':
+        break;
+
+      default:
+        // Unknown node — skip silently
+    }
+  }
+
+  // ── Expression walker ────────────────────────────────────────────────────
+  _walkExpr(node, scope, ctx) {
+    if (!node) return;
+    switch (node.type) {
+
+      case 'Identifier':
+        scope.markUsed(node.name);
+        break;
+
+      case 'AssignExpr':
+        // The target variable IS being written to — mark as used (it's live)
+        this._walkExpr(node.target, scope, ctx);
+        this._walkExpr(node.value,  scope, ctx);
+        break;
+
+      case 'UpdateExpr':
+        this._walkExpr(node.operand, scope, ctx);
+        break;
+
+      case 'BinaryExpr':
+      case 'PipeExpr':
+        this._walkExpr(node.left,  scope, ctx);
+        this._walkExpr(node.right, scope, ctx);
+        break;
+
+      case 'UnaryExpr':
+      case 'AwaitExpr':
+      case 'TypeofExpr':
+        this._walkExpr(node.operand, scope, ctx);
+        break;
+
+      case 'TernaryExpr':
+        this._walkExpr(node.cond,  scope, ctx);
+        this._walkExpr(node.then,  scope, ctx);
+        this._walkExpr(node.else_, scope, ctx);
+        break;
+
+      case 'CallExpr':
+      case 'OptCallExpr':
+        this._walkExpr(node.callee, scope, ctx);
+        for (const a of (node.args || [])) this._walkExpr(a, scope, ctx);
+        break;
+
+      case 'MemberExpr':
+      case 'OptMemberExpr':
+        this._walkExpr(node.obj, scope, ctx);
+        break;
+
+      case 'IndexExpr':
+      case 'OptIndexExpr':
+        this._walkExpr(node.obj, scope, ctx);
+        this._walkExpr(node.idx, scope, ctx);
+        break;
+
+      case 'NewExpr':
+        if (node.callee) this._walkExpr(node.callee, scope, ctx);
+        for (const a of (node.args || [])) this._walkExpr(a, scope, ctx);
+        break;
+
+      case 'ArrayExpr':
+        for (const i of (node.items || [])) if (i) this._walkExpr(i, scope, ctx);
+        break;
+
+      case 'ObjectExpr':
+        for (const p of (node.pairs || [])) if (p.value) this._walkExpr(p.value, scope, ctx);
+        break;
+
+      case 'SpreadExpr':
+        this._walkExpr(node.expr, scope, ctx);
+        break;
+
+      case 'LambdaExpr': {
+        const inner = new LintScope(scope, 'fn');
+        for (const p of (node.params || [])) {
+          const pe = inner.define(p.name, 'val', null);
+          pe.used = true;
+        }
+        this._walkExpr(node.body, inner, { ...ctx, inFn: true });
+        break;
+      }
+
+      case 'FnDecl': {
+        // Anonymous fn expression
+        if (node.name) {
+          const entry = scope.define(node.name, 'val', node.loc);
+          entry.used = true;
+        }
+        const inner = new LintScope(scope, 'fn');
+        for (const p of (node.params || [])) {
+          const pe = inner.define(p.name, 'val', null);
+          pe.used = true;
+        }
+        if (node.inline) {
+          this._walkExpr(node.body, inner, { ...ctx, inFn: true });
+        } else {
+          this._walkStmts(node.body, inner, { ...ctx, inFn: true });
+        }
+        break;
+      }
+
+      case 'TemplateLit':
+        this._walkTemplateParts(node.parts || [], scope, ctx);
+        break;
+
+      case 'CastExpr':
+      case 'AsConstExpr':
+      case 'SatisfiesExpr':
+      case 'IsExpr':
+      case 'NonNullExpr':
+        this._walkExpr(node.expr, scope, ctx);
+        break;
+
+      case 'RangeExpr':
+        this._walkExpr(node.start, scope, ctx);
+        this._walkExpr(node.end,   scope, ctx);
+        break;
+
+      case 'NumberLit':
+      case 'BoolLit':
+      case 'NullLit':
+      case 'StringLit':
+      case 'SelfExpr':
+        break;
+
+      default:
+        // Unknown expression — skip
+    }
+  }
+
+  // Template literal parts: {type:"text"|"expr", value: string}
+  // Re-parse each expr part so identifiers get marked used.
+  _walkTemplateParts(parts, scope, ctx) {
+    for (const p of parts) {
+      if (!p || p.type !== 'expr') continue;
+      try {
+        const tokens = new Lexer(p.value).tokenize();
+        const expr   = new Parser(tokens).parseExpr();
+        this._walkExpr(expr, scope, ctx);
+      } catch (_) {
+        // If re-parse fails, fall back to regex identifier scan
+        const re = /\b([a-zA-Z_][a-zA-Z0-9_]*)\b/g;
+        let m;
+        while ((m = re.exec(p.value)) !== null) scope.markUsed(m[1]);
+      }
+    }
+  }
+}
+
+// ── Shadow check (separate pass after unused-var) ─────────────────────────────
+// Walk AST again; when a new scope introduces a name already in a parent scope,
+// report a shadow warning.
+class ShadowChecker {
+  constructor() {
+    this.issues = [];
+  }
+
+  check(ast) {
+    this.issues = [];
+    // Build a flat "seen" set per ancestry path using the scope tree
+    this._walkStmts(ast.body, new LintScope(null, 'module'));
+    return this.issues;
+  }
+
+  _warn(name, inner, outer) {
+    this.issues.push(new LintIssue(
+      'shadow-val',
+      'warn',
+      `'${name}' shadows an outer declaration`,
+      `Rename one of the '${name}' variables to avoid confusion`,
+      inner
+    ));
+  }
+
+  _define(scope, name, loc) {
+    const outer = scope._lookupParent ? scope._lookupParent(name) : null;
+    if (outer && !isIgnoredName(name)) {
+      this._warn(name, loc, outer.loc);
+    }
+    scope.define(name, 'val', loc);
+  }
+
+  _walkStmts(stmts, scope) {
+    if (!stmts) return;
+    for (const node of stmts) this._walkStmt(node, scope);
+  }
+
+  _walkStmt(node, scope) {
+    if (!node) return;
+    switch (node.type) {
+      case 'VarDecl':
+        if (node.init) this._walkExpr(node.init, scope);
+        this._define(scope, node.name, node.loc);
+        break;
+
+      case 'DestructureDecl':
+        if (node.init) this._walkExpr(node.init, scope);
+        if (node.patternType === 'object') {
+          for (const p of node.pattern) this._define(scope, p.alias || p.name, node.loc);
+        } else {
+          for (const p of node.pattern) if (p) this._define(scope, p.name, node.loc);
+        }
+        break;
+
+      case 'FnDecl': {
+        if (node.name) this._define(scope, node.name, node.loc);
+        const inner = new LintScope(scope, 'fn');
+        for (const p of (node.params || [])) this._define(inner, p.name, node.loc);
+        if (node.inline) this._walkExpr(node.body, inner);
+        else             this._walkStmts(node.body, inner);
+        break;
+      }
+
+      case 'ClassDecl': {
+        this._define(scope, node.name, node.loc);
+        const cls = new LintScope(scope, 'class');
+        for (const m of (node.methods || [])) this._walkStmt(m, cls);
+        break;
+      }
+
+      case 'IfStmt':
+        this._walkExpr(node.cond, scope);
+        this._walkStmts(node.then,  new LintScope(scope, 'block'));
+        for (const ei of (node.elseifs || [])) {
+          this._walkExpr(ei.cond, scope);
+          this._walkStmts(ei.body, new LintScope(scope, 'block'));
+        }
+        if (node.else_) this._walkStmts(node.else_, new LintScope(scope, 'block'));
+        break;
+
+      case 'ForInStmt': {
+        this._walkExpr(node.iter, scope);
+        const fs = new LintScope(scope, 'block');
+        this._define(fs, node.var, node.loc);
+        this._walkStmts(node.body, fs);
+        break;
+      }
+
+      case 'WhileStmt':
+        this._walkExpr(node.cond, scope);
+        this._walkStmts(node.body, new LintScope(scope, 'block'));
+        break;
+
+      case 'DoWhileStmt':
+        this._walkStmts(node.body, new LintScope(scope, 'block'));
+        this._walkExpr(node.cond, scope);
+        break;
+
+      case 'MatchStmt':
+        this._walkExpr(node.subject, scope);
+        for (const arm of (node.arms || [])) {
+          const as_ = new LintScope(scope, 'block');
+          if (arm.pattern && arm.pattern.type === 'VariantPat') {
+            for (const b of arm.pattern.bindings) this._define(as_, b, node.loc);
+          }
+          if (arm.guard) this._walkExpr(arm.guard, as_);
+          if (arm.inline) {
+            const expr = arm.body && arm.body[0] && arm.body[0].expr
+              ? arm.body[0].expr : arm.body[0];
+            if (expr) this._walkExpr(expr, as_);
+          } else {
+            this._walkStmts(arm.body || [], as_);
+          }
+        }
+        break;
+
+      case 'ReturnStmt':   if (node.value) this._walkExpr(node.value, scope);   break;
+      case 'ThrowStmt':    this._walkExpr(node.value, scope);                   break;
+      case 'ExprStmt':     this._walkExpr(node.expr,  scope);                   break;
+
+      case 'TryCatchStmt':
+        this._walkStmts(node.tryBody, new LintScope(scope, 'block'));
+        if (node.catchBody) {
+          const cs = new LintScope(scope, 'block');
+          if (node.catchParam) this._define(cs, node.catchParam, node.loc);
+          this._walkStmts(node.catchBody, cs);
+        }
+        if (node.finallyBody) this._walkStmts(node.finallyBody, new LintScope(scope, 'block'));
+        break;
+
+      case 'ImportDecl':
+        if (node.defaultName)   this._define(scope, node.defaultName,   node.loc);
+        if (node.namespaceName) this._define(scope, node.namespaceName, node.loc);
+        for (const n of (node.names || [])) {
+          this._define(scope, typeof n === 'string' ? n : n.alias, node.loc);
+        }
+        break;
+
+      case 'ExportDecl':
+        this._walkStmt(node.isDefault
+          ? { type: 'ExprStmt', expr: node.decl } : node.decl, scope);
+        break;
+
+      default: break;
+    }
+  }
+
+  _walkExpr(node, scope) {
+    if (!node) return;
+    switch (node.type) {
+      case 'LambdaExpr': {
+        const inner = new LintScope(scope, 'fn');
+        for (const p of (node.params || [])) this._define(inner, p.name, null);
+        this._walkExpr(node.body, inner);
+        break;
+      }
+      case 'FnDecl': {
+        const inner = new LintScope(scope, 'fn');
+        for (const p of (node.params || [])) this._define(inner, p.name, null);
+        if (node.inline) this._walkExpr(node.body, inner);
+        else             this._walkStmts(node.body, inner);
+        break;
+      }
+      case 'BinaryExpr': case 'PipeExpr':
+        this._walkExpr(node.left, scope); this._walkExpr(node.right, scope); break;
+      case 'UnaryExpr': case 'AwaitExpr': case 'TypeofExpr':
+      case 'CastExpr':  case 'AsConstExpr': case 'SatisfiesExpr':
+      case 'IsExpr':    case 'NonNullExpr': case 'SpreadExpr':
+        this._walkExpr(node.operand || node.expr, scope); break;
+      case 'TernaryExpr':
+        this._walkExpr(node.cond,  scope);
+        this._walkExpr(node.then,  scope);
+        this._walkExpr(node.else_, scope); break;
+      case 'CallExpr': case 'OptCallExpr':
+        this._walkExpr(node.callee, scope);
+        for (const a of (node.args || [])) this._walkExpr(a, scope); break;
+      case 'MemberExpr': case 'OptMemberExpr':
+        this._walkExpr(node.obj, scope); break;
+      case 'IndexExpr': case 'OptIndexExpr':
+        this._walkExpr(node.obj, scope); this._walkExpr(node.idx, scope); break;
+      case 'NewExpr':
+        if (node.callee) this._walkExpr(node.callee, scope);
+        for (const a of (node.args || [])) this._walkExpr(a, scope); break;
+      case 'ArrayExpr':
+        for (const i of (node.items || [])) if (i) this._walkExpr(i, scope); break;
+      case 'ObjectExpr':
+        for (const p of (node.pairs || [])) if (p.value) this._walkExpr(p.value, scope); break;
+      case 'AssignExpr':
+        this._walkExpr(node.target, scope); this._walkExpr(node.value, scope); break;
+      case 'UpdateExpr':
+        this._walkExpr(node.operand, scope); break;
+      case 'RangeExpr':
+        this._walkExpr(node.start, scope); this._walkExpr(node.end, scope); break;
+      case 'TemplateLit':
+        for (const p of (node.parts || [])) {
+          if (!p || p.type !== 'expr') continue;
+          try {
+            const tokens = new Lexer(p.value).tokenize();
+            const expr   = new Parser(tokens).parseExpr();
+            this._walkExpr(expr, scope);
+          } catch (_) {
+            const re = /\b([a-zA-Z_][a-zA-Z0-9_]*)\b/g;
+            let m;
+            while ((m = re.exec(p.value)) !== null) {
+              const entry = scope.lookup ? scope.lookup(m[1]) : null;
+              // ShadowChecker only cares about definitions, not reads
+            }
+          }
+        }
+        break;
+      default: break;
+    }
+  }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+function lint(ast) {
+  const linter        = new Linter();
+  const shadowChecker = new ShadowChecker();
+
+  const unusedAndUnreachable = linter.lint(ast);
+  const shadows              = shadowChecker.check(ast);
+
+  return [...unusedAndUnreachable, ...shadows].sort((a, b) => {
+    const la = a.line || 0;
+    const lb = b.line || 0;
+    return la - lb;
+  });
+}
+
+module.exports = { lint, Linter, ShadowChecker, LintIssue };