@typescript-eslint/scope-manager 8.69.0: GlobalScope

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.GlobalScope 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.GlobalScope

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:a6a52cb9abc5701d164f8fcf17fd08f229ba0090700cd028fa7aef88e37b099c","contract":["GlobalScope can be directly instantiated with ScopeManager and Program AST node with null parent scope","analyze creates a GlobalScope instance as the root scope for Program AST","defineImplicitVariable registers environment global variables with specified readonly options into GlobalScope","addVariables dynamically binds variable identifiers into GlobalScope set and resolves matching references","GlobalScope tracks implicit global variables created by assignment to undeclared identifiers in script mode"],"goal":"verify @typescript-eslint/scope-manager.GlobalScope 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.GlobalScope"]},"contractCommand":["node","test/contract.cjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","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.GlobalScope"],"verifierAdapter":"node-typescript@1"}

{
  "name": "verify-typescript-eslint-scope-manager-global-scope",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "verify-typescript-eslint-scope-manager-global-scope",
      "version": "1.0.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": "verify-typescript-eslint-scope-manager-global-scope",
  "version": "1.0.0",
  "private": true,
  "description": "verify @typescript-eslint/scope-manager.GlobalScope in pkg:npm/@typescript-eslint/scope-manager@8.69.0",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "@typescript-eslint/scope-manager": "8.69.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @typescript-eslint/scope-manager.GlobalScope 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.GlobalScope"
  ]
}

const {
  analyze,
  GlobalScope,
  ScopeManager,
  ScopeType,
} = require('@typescript-eslint/scope-manager');

/**
 * Creates a GlobalScope directly with a given ScopeManager and Program AST node.
 *
 * @param {ScopeManager} scopeManager - The scope manager instance
 * @param {object} programNode - ESTree Program AST node
 * @returns {GlobalScope}
 */
function createDirectGlobalScope(scopeManager, programNode) {
  return new GlobalScope(scopeManager, programNode);
}

/**
 * Analyzes an AST and extracts the root GlobalScope.
 *
 * @param {object} ast - ESTree Program AST node
 * @param {object} [options] - Optional analysis configuration
 * @returns {{ scopeManager: ScopeManager, globalScope: GlobalScope }}
 */
function analyzeGlobalScope(ast, options) {
  const scopeManager = analyze(ast, options);
  const globalScope = scopeManager.scopes.find(
    (scope) => scope instanceof GlobalScope
  );
  return { scopeManager, globalScope };
}

/**
 * Registers implicit library variables or dynamic variables on a GlobalScope.
 *
 * @param {GlobalScope} globalScope - The GlobalScope to configure
 * @param {object} config - Configuration object
 * @param {Array<{ name: string, options: object }>} [config.implicitVariables] - Implicit lib variables
 * @param {string[]} [config.variableNames] - Names of variables to dynamically add
 */
function configureGlobalScope(globalScope, config = {}) {
  if (!globalScope || !(globalScope instanceof GlobalScope)) {
    throw new TypeError('Expected an instance of GlobalScope');
  }
  if (config.implicitVariables) {
    for (const item of config.implicitVariables) {
      globalScope.defineImplicitVariable(item.name, item.options);
    }
  }
  if (config.variableNames) {
    globalScope.addVariables(config.variableNames);
  }
}

/**
 * Extracts metadata from a GlobalScope instance.
 *
 * @param {GlobalScope} globalScope - The GlobalScope to inspect
 * @returns {{
 *   type: string,
 *   upper: null,
 *   blockType: string | null,
 *   variableNames: string[],
 *   implicitVariableNames: string[],
 *   childScopeTypes: string[]
 * }}
 */
function getGlobalScopeMetadata(globalScope) {
  if (!globalScope || !(globalScope instanceof GlobalScope)) {
    throw new TypeError('Expected an instance of GlobalScope');
  }
  return {
    type: globalScope.type,
    upper: globalScope.upper,
    blockType: globalScope.block ? globalScope.block.type : null,
    variableNames: Array.from(globalScope.set.keys()),
    implicitVariableNames: Array.from(globalScope.implicit.set.keys()),
    childScopeTypes: globalScope.childScopes.map((child) => child.type),
  };
}

module.exports = {
  createDirectGlobalScope,
  analyzeGlobalScope,
  configureGlobalScope,
  getGlobalScopeMetadata,
};

const assert = require('node:assert/strict');
const {
  analyze,
  GlobalScope,
  ScopeManager,
  ScopeType,
} = require('@typescript-eslint/scope-manager');
const {
  createDirectGlobalScope,
  analyzeGlobalScope,
  configureGlobalScope,
  getGlobalScopeMetadata,
} = require('../src/index.js');

// 1. GlobalScope can be directly instantiated with ScopeManager and Program AST node with null parent scope
const manager = new ScopeManager({});
const programNode = { type: 'Program', sourceType: 'script', body: [] };
const directGlobalScope = createDirectGlobalScope(manager, programNode);

assert.ok(directGlobalScope instanceof GlobalScope, 'Instance should be GlobalScope');
assert.strictEqual(directGlobalScope.type, ScopeType.global, 'Scope type should match ScopeType.global');
assert.strictEqual(directGlobalScope.type, 'global', 'Scope type should be "global"');
assert.strictEqual(directGlobalScope.upper, null, 'GlobalScope has no parent scope');
assert.strictEqual(directGlobalScope.block, programNode, 'Block should reference the program AST node');

const directMeta = getGlobalScopeMetadata(directGlobalScope);
assert.strictEqual(directMeta.type, 'global');
assert.strictEqual(directMeta.upper, null);
assert.strictEqual(directMeta.blockType, 'Program');

// 2. analyze creates a GlobalScope instance as the root scope for Program AST
const programAst = {
  type: 'Program',
  sourceType: 'script',
  body: [
    {
      type: 'VariableDeclaration',
      kind: 'var',
      declarations: [
        {
          type: 'VariableDeclarator',
          id: { type: 'Identifier', name: 'appConfig', range: [4, 13] },
          init: { type: 'Literal', value: 1, raw: '1', range: [16, 17] },
          range: [4, 17],
        },
      ],
      range: [0, 18],
    },
    {
      type: 'FunctionDeclaration',
      id: { type: 'Identifier', name: 'initialize', range: [28, 38] },
      params: [],
      body: { type: 'BlockStatement', body: [], range: [41, 43] },
      range: [19, 43],
    },
  ],
  range: [0, 43],
  loc: { start: { line: 1, column: 0 }, end: { line: 3, column: 1 } },
  comments: [],
  tokens: [],
};

const { scopeManager: analyzedManager, globalScope: analyzedGlobalScope } =
  analyzeGlobalScope(programAst);

assert.ok(analyzedGlobalScope instanceof GlobalScope, 'Analyzed root scope should be GlobalScope');
assert.strictEqual(analyzedGlobalScope.type, ScopeType.global);
assert.strictEqual(analyzedGlobalScope.upper, null);
assert.ok(analyzedGlobalScope.set.has('appConfig'), 'Variable appConfig should exist in GlobalScope');
assert.ok(analyzedGlobalScope.set.has('initialize'), 'Function initialize should exist in GlobalScope');
assert.strictEqual(analyzedGlobalScope.childScopes.length, 1, 'GlobalScope should contain child scope for function');
assert.strictEqual(analyzedGlobalScope.childScopes[0].type, ScopeType.function);
assert.strictEqual(analyzedGlobalScope.childScopes[0].upper, analyzedGlobalScope);

const analyzedMeta = getGlobalScopeMetadata(analyzedGlobalScope);
assert.deepStrictEqual(analyzedMeta.childScopeTypes, ['function']);
assert.ok(analyzedMeta.variableNames.includes('appConfig'));
assert.ok(analyzedMeta.variableNames.includes('initialize'));

// 3. defineImplicitVariable registers environment global variables with specified readonly options into GlobalScope
configureGlobalScope(directGlobalScope, {
  implicitVariables: [
    { name: 'window', options: { writeable: false, isValueVariable: true } },
    { name: 'customLogger', options: { writeable: true, isValueVariable: true } },
  ],
});

assert.ok(directGlobalScope.set.has('window'), 'Implicit window variable should be registered');
const windowVar = directGlobalScope.set.get('window');
assert.strictEqual(windowVar.writeable, false, 'window should be marked readonly / non-writable');
assert.strictEqual(windowVar.isValueVariable, true, 'window should be marked as value variable');

assert.ok(directGlobalScope.set.has('customLogger'), 'Implicit customLogger variable should be registered');
const loggerVar = directGlobalScope.set.get('customLogger');
assert.strictEqual(loggerVar.writeable, true, 'customLogger should be marked writable');

// 4. addVariables dynamically binds variable identifiers into GlobalScope set and resolves matching references
const throughAst = {
  type: 'Program',
  sourceType: 'script',
  body: [
    {
      type: 'ExpressionStatement',
      expression: {
        type: 'Identifier',
        name: 'dynamicPayload',
        range: [0, 14],
      },
      range: [0, 15],
    },
  ],
  range: [0, 15],
  loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 15 } },
  comments: [],
  tokens: [],
};

const { globalScope: throughScope } = analyzeGlobalScope(throughAst);
assert.ok(
  throughScope.through.some((ref) => ref.identifier.name === 'dynamicPayload'),
  'dynamicPayload should initially be in through references'
);

configureGlobalScope(throughScope, {
  variableNames: ['dynamicPayload'],
});

assert.ok(throughScope.set.has('dynamicPayload'), 'dynamicPayload should be added to scope set');
assert.strictEqual(
  throughScope.through.some((ref) => ref.identifier.name === 'dynamicPayload'),
  false,
  'dynamicPayload should no longer be in through references after resolution'
);

// 5. GlobalScope tracks implicit global variables created by assignment to undeclared identifiers in script mode
const undeclaredAssignAst = {
  type: 'Program',
  sourceType: 'script',
  body: [
    {
      type: 'ExpressionStatement',
      expression: {
        type: 'AssignmentExpression',
        operator: '=',
        left: { type: 'Identifier', name: 'undeclaredGlobal', range: [0, 16] },
        right: { type: 'Literal', value: 100, raw: '100', range: [19, 22] },
        range: [0, 22],
      },
      range: [0, 23],
    },
  ],
  range: [0, 23],
  loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 23 } },
  comments: [],
  tokens: [],
};

const { globalScope: undeclaredScope } = analyzeGlobalScope(undeclaredAssignAst);
assert.ok(
  undeclaredScope.implicit.set.has('undeclaredGlobal'),
  'Undeclared assignment should create an implicit global variable in implicit.set'
);
const implicitVar = undeclaredScope.implicit.variables.find(
  (v) => v.name === 'undeclaredGlobal'
);
assert.ok(implicitVar, 'Implicit variable should be recorded in implicit.variables');
assert.strictEqual(implicitVar.defs.length, 1);
assert.strictEqual(
  implicitVar.defs[0].type,
  'ImplicitGlobalVariable',
  'Definition type should be ImplicitGlobalVariable'
);

// Error handling validation
assert.throws(
  () => getGlobalScopeMetadata(null),
  /Expected an instance of GlobalScope/,
  'getGlobalScopeMetadata should throw TypeError for invalid scope argument'
);
assert.throws(
  () => configureGlobalScope(null),
  /Expected an instance of GlobalScope/,
  'configureGlobalScope should throw TypeError for invalid scope argument'
);

console.log('All contract assertions passed successfully.');