@typescript-eslint/scope-manager 8.69.0: TSEnumScope

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

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:913064f0fa1b35129131d7c4d3f4187887924aad5a87de2a50c90c8b163fd758","contract":["TSEnumScope extends ScopeBase and has type ScopeType.tsEnum","analyze creates a TSEnumScope for TSEnumDeclaration AST nodes and associates it with the declaration block","TSEnumScope registers enum members as scoped variables with TSEnumMemberDefinition","TSEnumScope upper scope contains the enum name identifier with TSEnumNameDefinition","references within enum member initializers are resolved to variables within the TSEnumScope","TSEnumScope can be instantiated directly or nested via ScopeManager.nestTSEnumScope"],"goal":"verify @typescript-eslint/scope-manager.TSEnumScope 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.TSEnumScope"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","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.TSEnumScope"],"verifierAdapter":"node-typescript@1"}

import {
  TSEnumScope,
  ScopeManager,
  ScopeType,
  analyze,
  TSEnumMemberDefinition,
  TSEnumNameDefinition,
} from '@typescript-eslint/scope-manager';

/**
 * Creates an AST for a TypeScript enum declaration with the given name and members.
 *
 * @param {string} name - Name of the enum.
 * @param {Array<{ name: string, initializer?: object }>} members - Enum member definitions.
 * @returns {object} AST node for Program wrapping TSEnumDeclaration.
 */
export function createEnumAST(name, members = []) {
  return {
    type: 'Program',
    body: [
      {
        type: 'TSEnumDeclaration',
        id: { type: 'Identifier', name },
        body: {
          type: 'TSEnumBody',
          members: members.map((m) => ({
            type: 'TSEnumMember',
            id: { type: 'Identifier', name: m.name },
            initializer: m.initializer ?? null,
          })),
        },
      },
    ],
    sourceType: 'module',
  };
}

/**
 * Analyzes an AST and retrieves all TSEnumScope instances found in the scope manager.
 *
 * @param {object} ast - AST to analyze.
 * @returns {{ scopeManager: ScopeManager, enumScopes: TSEnumScope[] }}
 */
export function analyzeEnumScopes(ast) {
  const scopeManager = analyze(ast);
  const enumScopes = scopeManager.scopes.filter((s) => s instanceof TSEnumScope);
  return { scopeManager, enumScopes };
}

/**
 * Finds a TSEnumScope by its enum declaration identifier name.
 *
 * @param {ScopeManager} scopeManager - ScopeManager instance.
 * @param {string} name - Name of the enum.
 * @returns {TSEnumScope | undefined}
 */
export function findEnumScopeByName(scopeManager, name) {
  return scopeManager.scopes.find(
    (s) => s instanceof TSEnumScope && s.block?.id?.name === name
  );
}

/**
 * Directly creates and nests a TSEnumScope within a ScopeManager instance.
 *
 * @param {ScopeManager} scopeManager - The target scope manager.
 * @param {object} enumBlock - TSEnumDeclaration AST node.
 * @returns {TSEnumScope}
 */
export function nestEnumScope(scopeManager, enumBlock) {
  return scopeManager.nestTSEnumScope(enumBlock);
}

export {
  TSEnumScope,
  ScopeManager,
  ScopeType,
  analyze,
  TSEnumMemberDefinition,
  TSEnumNameDefinition,
};

{
  "name": "sample-typescript-eslint-scope-manager-tsenumscope",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-typescript-eslint-scope-manager-tsenumscope",
      "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": "sample-typescript-eslint-scope-manager-tsenumscope",
  "version": "1.0.0",
  "private": true,
  "description": "verify @typescript-eslint/scope-manager.TSEnumScope in pkg:npm/@typescript-eslint/scope-manager@8.69.0",
  "type": "module",
  "main": "index.mjs",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@typescript-eslint/scope-manager": "8.69.0"
  }
}

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

import assert from 'node:assert/strict';
import {
  TSEnumScope,
  ScopeManager,
  ScopeType,
  analyze,
  TSEnumMemberDefinition,
  TSEnumNameDefinition,
  createEnumAST,
  analyzeEnumScopes,
  findEnumScopeByName,
  nestEnumScope,
} from '../index.mjs';

// 1. TSEnumScope extends ScopeBase and has type ScopeType.tsEnum
{
  const manager = new ScopeManager({});
  const programScope = manager.nestGlobalScope({ type: 'Program', body: [] });
  const enumNode = {
    type: 'TSEnumDeclaration',
    id: { type: 'Identifier', name: 'Status' },
    body: { type: 'TSEnumBody', members: [] },
  };
  const directScope = new TSEnumScope(manager, programScope, enumNode);
  assert.ok(directScope instanceof TSEnumScope, 'Must be instance of TSEnumScope');
  assert.strictEqual(directScope.type, ScopeType.tsEnum, 'Scope type must match ScopeType.tsEnum');
  assert.strictEqual(directScope.type, 'tsEnum', 'Scope type string must be tsEnum');
  assert.strictEqual(directScope.block, enumNode, 'Scope block must match the AST node');
  assert.strictEqual(directScope.upper, programScope, 'Upper scope must match parent scope');
}

// 2. analyze creates a TSEnumScope for TSEnumDeclaration AST nodes and associates it with the declaration block
{
  const ast = createEnumAST('Direction', [
    { name: 'North', initializer: { type: 'Literal', value: 1 } },
    { name: 'South', initializer: { type: 'Literal', value: 2 } },
  ]);
  const { scopeManager, enumScopes } = analyzeEnumScopes(ast);
  assert.strictEqual(enumScopes.length, 1, 'Should find exactly one TSEnumScope');
  const foundScope = findEnumScopeByName(scopeManager, 'Direction');
  assert.ok(foundScope, 'Should locate Direction TSEnumScope by name');
  assert.strictEqual(foundScope, enumScopes[0]);
  assert.strictEqual(foundScope.block.id.name, 'Direction');
}

// 3. TSEnumScope registers enum members as scoped variables with TSEnumMemberDefinition
{
  const ast = createEnumAST('Color', [
    { name: 'Red', initializer: { type: 'Literal', value: '#ff0000' } },
    { name: 'Green', initializer: { type: 'Literal', value: '#00ff00' } },
    { name: 'Blue', initializer: { type: 'Literal', value: '#0000ff' } },
  ]);
  const { scopeManager } = analyzeEnumScopes(ast);
  const colorScope = findEnumScopeByName(scopeManager, 'Color');
  assert.ok(colorScope, 'Color enum scope must exist');
  assert.strictEqual(colorScope.variables.length, 3, 'Must contain 3 enum member variables');

  for (const name of ['Red', 'Green', 'Blue']) {
    const memberVar = colorScope.set.get(name);
    assert.ok(memberVar, `Variable ${name} must exist in enum scope`);
    assert.strictEqual(memberVar.name, name);
    assert.strictEqual(memberVar.defs.length, 1);
    assert.ok(
      memberVar.defs[0] instanceof TSEnumMemberDefinition,
      `Definition for ${name} must be a TSEnumMemberDefinition`
    );
  }
}

// 4. TSEnumScope upper scope contains the enum name identifier with TSEnumNameDefinition
{
  const ast = createEnumAST('Priority', [
    { name: 'Low', initializer: { type: 'Literal', value: 0 } },
    { name: 'High', initializer: { type: 'Literal', value: 1 } },
  ]);
  const { scopeManager } = analyzeEnumScopes(ast);
  const priorityScope = findEnumScopeByName(scopeManager, 'Priority');
  const upperScope = priorityScope.upper;
  const enumVariable = upperScope.set.get('Priority');
  assert.ok(enumVariable, 'Priority variable must exist in enclosing scope');
  assert.strictEqual(enumVariable.name, 'Priority');
  assert.strictEqual(enumVariable.defs.length, 1);
  assert.ok(
    enumVariable.defs[0] instanceof TSEnumNameDefinition,
    'Enum variable definition must be a TSEnumNameDefinition'
  );
}

// 5. references within enum member initializers are resolved to variables within the TSEnumScope
{
  const astWithRefs = {
    type: 'Program',
    body: [
      {
        type: 'TSEnumDeclaration',
        id: { type: 'Identifier', name: 'FilePermissions' },
        body: {
          type: 'TSEnumBody',
          members: [
            {
              type: 'TSEnumMember',
              id: { type: 'Identifier', name: 'Read' },
              initializer: { type: 'Literal', value: 4 },
            },
            {
              type: 'TSEnumMember',
              id: { type: 'Identifier', name: 'Write' },
              initializer: { type: 'Literal', value: 2 },
            },
            {
              type: 'TSEnumMember',
              id: { type: 'Identifier', name: 'ReadWrite' },
              initializer: {
                type: 'BinaryExpression',
                operator: '|',
                left: { type: 'Identifier', name: 'Read' },
                right: { type: 'Identifier', name: 'Write' },
              },
            },
          ],
        },
      },
    ],
    sourceType: 'module',
  };
  const { scopeManager } = analyzeEnumScopes(astWithRefs);
  const permScope = findEnumScopeByName(scopeManager, 'FilePermissions');
  assert.ok(permScope, 'FilePermissions scope must exist');
  assert.strictEqual(permScope.references.length, 2, 'Must have 2 references in initializer expressions');

  const readVar = permScope.set.get('Read');
  const writeVar = permScope.set.get('Write');
  const readRef = permScope.references.find((r) => r.identifier.name === 'Read');
  const writeRef = permScope.references.find((r) => r.identifier.name === 'Write');

  assert.ok(readRef, 'Read reference must exist');
  assert.ok(writeRef, 'Write reference must exist');
  assert.strictEqual(readRef.resolved, readVar, 'Read reference must resolve to Read enum member variable');
  assert.strictEqual(writeRef.resolved, writeVar, 'Write reference must resolve to Write enum member variable');
}

// 6. TSEnumScope can be instantiated directly or nested via ScopeManager.nestTSEnumScope
{
  const manager = new ScopeManager({});
  manager.nestGlobalScope({ type: 'Program', body: [] });
  const enumAstNode = {
    type: 'TSEnumDeclaration',
    id: { type: 'Identifier', name: 'NestedEnum' },
  };
  const nested = nestEnumScope(manager, enumAstNode);
  assert.ok(nested instanceof TSEnumScope, 'Nested scope must be an instance of TSEnumScope');
  assert.ok(manager.scopes.includes(nested), 'Manager scopes list must contain nested enum scope');
  assert.strictEqual(nested.block, enumAstNode, 'Nested scope block must match node');
  assert.strictEqual(nested.type, ScopeType.tsEnum, 'Nested scope type must be tsEnum');
}

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