@typescript-eslint/scope-manager 8.69.0: analyze

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify @typescript-eslint/scope-manager.analyze in pkg:npm/%40typescript-eslint/scope-manager@8.69.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40typescript-eslint/scope-manager@8.69.0
Demonstrate these symbols/APIs:
  - @typescript-eslint/scope-manager.analyze

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:a4258f227fc485d659344e57ad0792765971d58b36f722d9a75050c914409b99","contract":["analyze produces a ScopeManager containing global and module scopes for a module Program AST","analyze resolves variable declarations and creates definitions and references in the enclosing scope","analyze creates a function scope with arguments and parameter variables for FunctionDeclaration","analyze creates a block scope for block-scoped declarations inside BlockStatement","analyze creates type variables with isTypeVariable set to true for TSTypeAliasDeclaration","analyze respects globalReturn option by creating a function scope directly inside global scope","analyze configures global built-in variables based on the specified lib option"],"goal":"verify @typescript-eslint/scope-manager.analyze in pkg:npm/%40typescript-eslint/scope-manager@8.69.0","kind":"HOW","packages":["pkg:npm/%40typescript-eslint/scope-manager@8.69.0"],"schemaVersion":1,"symbols":["@typescript-eslint/scope-manager.analyze"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40typescript-eslint/scope-manager@8.69.0"],"schemaVersion":1,"subject":"pkg:npm/%40typescript-eslint/scope-manager@8.69.0","symbols":["@typescript-eslint/scope-manager.analyze"],"verifierAdapter":"node-typescript@1"}

import { analyze } from '@typescript-eslint/scope-manager';

/**
 * Analyzes an AST and returns the ScopeManager instance.
 * @param {object} ast - TSESTree.Program AST node
 * @param {object} [options] - AnalyzeOptions
 * @returns {import('@typescript-eslint/scope-manager').ScopeManager}
 */
export function analyzeProgram(ast, options = {}) {
  return analyze(ast, options);
}

/**
 * Finds a scope by its type within a ScopeManager.
 * @param {import('@typescript-eslint/scope-manager').ScopeManager} scopeManager
 * @param {string} scopeType
 * @returns {import('@typescript-eslint/scope-manager').Scope|undefined}
 */
export function findScopeByType(scopeManager, scopeType) {
  return scopeManager.scopes.find((s) => s.type === scopeType);
}

/**
 * Gets a variable by name from a given scope.
 * @param {import('@typescript-eslint/scope-manager').Scope} scope
 * @param {string} name
 * @returns {import('@typescript-eslint/scope-manager').Variable|undefined}
 */
export function getVariableFromScope(scope, name) {
  return scope.set.get(name);
}

export { analyze };
export default analyze;

{
  "name": "sample-typescript-eslint-scope-manager",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-typescript-eslint-scope-manager",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@typescript-eslint/scope-manager": "8.69.0"
      }
    },
    "node_modules/@typescript-eslint/scope-manager": {
      "version": "8.69.0",
      "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.69.0.tgz",
      "integrity": "sha512-ewfspqWvSxKSOaplqAUNbaSFO0eB6w1EtQ+esfYFRm3614Ty4uNtExkcbgd6nWsXphbqKyf9ZYdbZdv2xEoWEQ==",
      "license": "MIT",
      "dependencies": {
        "@typescript-eslint/types": "8.69.0",
        "@typescript-eslint/visitor-keys": "8.69.0"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/typescript-eslint"
      }
    },
    "node_modules/@typescript-eslint/types": {
      "version": "8.69.0",
      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.69.0.tgz",
      "integrity": "sha512-K3VrubUPhlo9VDBS6QdI8YB5j7ClpqLRdefcz6PFrhnwicehBweqQ9Evhl4l+FYz0HdDmMqIiSX0aldGRYtDCA==",
      "license": "MIT",
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/typescript-eslint"
      }
    },
    "node_modules/@typescript-eslint/visitor-keys": {
      "version": "8.69.0",
      "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.69.0.tgz",
      "integrity": "sha512-+rmdgPA+EXkNgKYvHvFfhrs35utXbwaC5PGpDquSXcoXQDKUA5UjV0LmTucG/4JXkM31BTu4TilHtrN8IVBe8w==",
      "license": "MIT",
      "dependencies": {
        "@typescript-eslint/types": "8.69.0",
        "eslint-visitor-keys": "^5.0.0"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/typescript-eslint"
      }
    },
    "node_modules/eslint-visitor-keys": {
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-5.0.1.tgz",
      "integrity": "sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==",
      "license": "Apache-2.0",
      "engines": {
        "node": "^20.19.0 || ^22.13.0 || >=24"
      },
      "funding": {
        "url": "https://opencollective.com/eslint"
      }
    }
  }
}

{
  "name": "sample-typescript-eslint-scope-manager",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@typescript-eslint/scope-manager": "8.69.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @typescript-eslint/scope-manager.analyze in pkg:npm/%40typescript-eslint/scope-manager@8.69.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40typescript-eslint/scope-manager@8.69.0"
  ],
  "symbols": [
    "@typescript-eslint/scope-manager.analyze"
  ]
}

import assert from 'node:assert/strict';
import analyze, {
  analyzeProgram,
  findScopeByType,
  getVariableFromScope,
} from '../index.js';

// 1. analyze produces a ScopeManager containing global and module scopes for a module Program AST
{
  const ast = {
    type: 'Program',
    range: [0, 10],
    loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 10 } },
    body: [],
    sourceType: 'module',
    comments: [],
    tokens: [],
  };

  const sm = analyze(ast, { sourceType: 'module' });
  assert.ok(sm);
  assert.equal(sm.scopes.length, 2);
  assert.equal(sm.scopes[0].type, 'global');
  assert.equal(sm.scopes[1].type, 'module');
  assert.equal(sm.globalScope, sm.scopes[0]);
}

// 2. analyze resolves variable declarations and creates definitions and references in the enclosing scope
{
  const varId = {
    type: 'Identifier',
    name: 'greeting',
    range: [6, 14],
    loc: { start: { line: 1, column: 6 }, end: { line: 1, column: 14 } },
  };
  const varDeclarator = {
    type: 'VariableDeclarator',
    range: [6, 24],
    loc: { start: { line: 1, column: 6 }, end: { line: 1, column: 24 } },
    id: varId,
    init: {
      type: 'Literal',
      value: 'hello',
      raw: "'hello'",
      range: [17, 24],
      loc: { start: { line: 1, column: 17 }, end: { line: 1, column: 24 } },
    },
  };
  const varDecl = {
    type: 'VariableDeclaration',
    kind: 'const',
    range: [0, 25],
    loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 25 } },
    declarations: [varDeclarator],
  };
  const refId = {
    type: 'Identifier',
    name: 'greeting',
    range: [34, 42],
    loc: { start: { line: 2, column: 8 }, end: { line: 2, column: 16 } },
  };
  const exprStmt = {
    type: 'ExpressionStatement',
    range: [26, 43],
    loc: { start: { line: 2, column: 0 }, end: { line: 2, column: 17 } },
    expression: {
      type: 'CallExpression',
      callee: {
        type: 'Identifier',
        name: 'print',
        range: [26, 31],
        loc: { start: { line: 2, column: 0 }, end: { line: 2, column: 5 } },
      },
      arguments: [refId],
      optional: false,
      range: [26, 43],
      loc: { start: { line: 2, column: 0 }, end: { line: 2, column: 17 } },
    },
  };
  const ast = {
    type: 'Program',
    range: [0, 43],
    loc: { start: { line: 1, column: 0 }, end: { line: 2, column: 17 } },
    body: [varDecl, exprStmt],
    sourceType: 'module',
    comments: [],
    tokens: [],
  };

  const sm = analyzeProgram(ast, { sourceType: 'module' });
  const moduleScope = findScopeByType(sm, 'module');
  assert.ok(moduleScope);

  const greetingVar = getVariableFromScope(moduleScope, 'greeting');
  assert.ok(greetingVar);
  assert.equal(greetingVar.name, 'greeting');
  assert.equal(greetingVar.defs.length, 1);
  assert.equal(greetingVar.defs[0].type, 'Variable');

  const declared = sm.getDeclaredVariables(varDecl);
  assert.equal(declared.length, 1);
  assert.equal(declared[0], greetingVar);

  const greetingRef = moduleScope.references.find(
    (r) => r.identifier.name === 'greeting'
  );
  assert.ok(greetingRef);
  assert.equal(greetingRef.resolved, greetingVar);
}

// 3. analyze creates a function scope with arguments and parameter variables for FunctionDeclaration
{
  const paramA = {
    type: 'Identifier',
    name: 'a',
    range: [13, 14],
    loc: { start: { line: 1, column: 13 }, end: { line: 1, column: 14 } },
    decorators: [],
  };
  const paramB = {
    type: 'Identifier',
    name: 'b',
    range: [16, 17],
    loc: { start: { line: 1, column: 16 }, end: { line: 1, column: 17 } },
    decorators: [],
  };
  const fnDecl = {
    type: 'FunctionDeclaration',
    id: {
      type: 'Identifier',
      name: 'add',
      range: [9, 12],
      loc: { start: { line: 1, column: 9 }, end: { line: 1, column: 12 } },
    },
    generator: false,
    async: false,
    params: [paramA, paramB],
    body: {
      type: 'BlockStatement',
      body: [
        {
          type: 'ReturnStatement',
          argument: {
            type: 'BinaryExpression',
            operator: '+',
            left: {
              type: 'Identifier',
              name: 'a',
              range: [34, 35],
              loc: { start: { line: 2, column: 9 }, end: { line: 2, column: 10 } },
            },
            right: {
              type: 'Identifier',
              name: 'b',
              range: [38, 39],
              loc: { start: { line: 2, column: 13 }, end: { line: 2, column: 14 } },
            },
            range: [34, 39],
            loc: { start: { line: 2, column: 9 }, end: { line: 2, column: 14 } },
          },
          range: [27, 40],
          loc: { start: { line: 2, column: 2 }, end: { line: 2, column: 15 } },
        },
      ],
      range: [19, 42],
      loc: { start: { line: 1, column: 19 }, end: { line: 3, column: 1 } },
    },
    range: [0, 42],
    loc: { start: { line: 1, column: 0 }, end: { line: 3, column: 1 } },
  };
  const ast = {
    type: 'Program',
    range: [0, 42],
    loc: { start: { line: 1, column: 0 }, end: { line: 3, column: 1 } },
    body: [fnDecl],
    sourceType: 'module',
    comments: [],
    tokens: [],
  };

  const sm = analyze(ast, { sourceType: 'module' });
  const fnScope = sm.acquire(fnDecl);
  assert.ok(fnScope);
  assert.equal(fnScope.type, 'function');
  assert.equal(fnScope.block, fnDecl);

  const varNames = fnScope.variables.map((v) => v.name);
  assert.ok(varNames.includes('arguments'));
  assert.ok(varNames.includes('a'));
  assert.ok(varNames.includes('b'));

  const aVar = fnScope.set.get('a');
  assert.ok(aVar);
  assert.equal(aVar.defs[0].type, 'Parameter');
}

// 4. analyze creates a block scope for block-scoped declarations inside BlockStatement
{
  const blockStmt = {
    type: 'BlockStatement',
    body: [
      {
        type: 'VariableDeclaration',
        kind: 'let',
        range: [4, 18],
        loc: { start: { line: 2, column: 2 }, end: { line: 2, column: 16 } },
        declarations: [
          {
            type: 'VariableDeclarator',
            id: {
              type: 'Identifier',
              name: 'scopedVal',
              range: [8, 17],
              loc: { start: { line: 2, column: 6 }, end: { line: 2, column: 15 } },
            },
            init: null,
            range: [8, 17],
            loc: { start: { line: 2, column: 6 }, end: { line: 2, column: 15 } },
          },
        ],
      },
    ],
    range: [0, 20],
    loc: { start: { line: 1, column: 0 }, end: { line: 3, column: 1 } },
  };
  const ast = {
    type: 'Program',
    range: [0, 20],
    loc: { start: { line: 1, column: 0 }, end: { line: 3, column: 1 } },
    body: [blockStmt],
    sourceType: 'module',
    comments: [],
    tokens: [],
  };

  const sm = analyze(ast, { sourceType: 'module' });
  const blockScope = sm.scopes.find((s) => s.type === 'block');
  assert.ok(blockScope);
  assert.equal(blockScope.block, blockStmt);
  assert.ok(blockScope.set.has('scopedVal'));

  const moduleScope = findScopeByType(sm, 'module');
  assert.equal(moduleScope.set.has('scopedVal'), false);
}

// 5. analyze creates type variables with isTypeVariable set to true for TSTypeAliasDeclaration
{
  const typeAliasNode = {
    type: 'TSTypeAliasDeclaration',
    id: {
      type: 'Identifier',
      name: 'UserID',
      range: [5, 11],
      loc: { start: { line: 1, column: 5 }, end: { line: 1, column: 11 } },
    },
    typeAnnotation: {
      type: 'TSStringKeyword',
      range: [14, 20],
      loc: { start: { line: 1, column: 14 }, end: { line: 1, column: 20 } },
    },
    range: [0, 21],
    loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 21 } },
  };
  const ast = {
    type: 'Program',
    range: [0, 21],
    loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 21 } },
    body: [typeAliasNode],
    sourceType: 'module',
    comments: [],
    tokens: [],
  };

  const sm = analyze(ast, { sourceType: 'module' });
  const moduleScope = findScopeByType(sm, 'module');
  assert.ok(moduleScope);

  const typeVar = moduleScope.set.get('UserID');
  assert.ok(typeVar);
  assert.equal(typeVar.name, 'UserID');
  assert.equal(typeVar.isTypeVariable, true);
  assert.equal(typeVar.defs[0].type, 'Type');
}

// 6. analyze respects globalReturn option by creating a function scope directly inside global scope
{
  const ast = {
    type: 'Program',
    range: [0, 10],
    loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 10 } },
    body: [],
    sourceType: 'script',
    comments: [],
    tokens: [],
  };

  const smStandard = analyze(ast, {
    sourceType: 'script',
    globalReturn: false,
  });
  assert.equal(smStandard.scopes.length, 1);
  assert.equal(smStandard.scopes[0].type, 'global');

  const smGlobalReturn = analyze(ast, {
    sourceType: 'script',
    globalReturn: true,
  });
  assert.equal(smGlobalReturn.scopes.length, 2);
  assert.equal(smGlobalReturn.scopes[0].type, 'global');
  assert.equal(smGlobalReturn.scopes[1].type, 'function');
  assert.equal(smGlobalReturn.scopes[1].upper, smGlobalReturn.scopes[0]);
}

// 7. analyze configures global built-in variables based on the specified lib option
{
  const ast = {
    type: 'Program',
    range: [0, 10],
    loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 10 } },
    body: [],
    sourceType: 'script',
    comments: [],
    tokens: [],
  };

  const smEs5 = analyze(ast, { sourceType: 'script', lib: ['es5'] });
  assert.equal(smEs5.globalScope.set.has('Map'), false);
  assert.equal(smEs5.globalScope.set.has('Set'), false);
  assert.equal(smEs5.globalScope.set.has('Object'), true);

  const smEs2015 = analyze(ast, { sourceType: 'script', lib: ['es2015'] });
  assert.equal(smEs2015.globalScope.set.has('Map'), true);
  assert.equal(smEs2015.globalScope.set.has('Set'), true);
}

console.log('Contract tests passed successfully.');