@types/js-yaml 4.0.9: types

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 @types/js-yaml.types in pkg:npm/%40types/js-yaml@4.0.9
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40types/js-yaml@4.0.9
Demonstrate these symbols/APIs:
  - @types/js-yaml.types

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:b3d5a1ecc6848ff7eb394f12abcbfac52593965493ff4a90c123b55637bfa845","contract":["package.json defines types entry point index.d.ts and conditional exports mapping default and import types","The referenced index.d.ts declaration file exists and defines core TypeScript function declarations load, loadAll, and dump","index.d.ts defines option interfaces LoadOptions, DumpOptions, TypeConstructorOptions, and SchemaDefinition","index.d.ts defines classes Type, Schema, and YAMLException with Mark and State interfaces","index.d.ts defines built-in schema constants FAILSAFE_SCHEMA, JSON_SCHEMA, CORE_SCHEMA, and DEFAULT_SCHEMA","index.d.mts exists and provides ESM wildcard and default type re-exports from index.js"],"goal":"verify @types/js-yaml.types in pkg:npm/%40types/js-yaml@4.0.9","kind":"HOW","packages":["pkg:npm/%40types/js-yaml@4.0.9"],"schemaVersion":1,"symbols":["@types/js-yaml.types"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","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/%40types/js-yaml@4.0.9"],"schemaVersion":1,"subject":"pkg:npm/%40types/js-yaml@4.0.9","symbols":["@types/js-yaml.types"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-types-js-yaml-types",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-types-js-yaml-types",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@types/js-yaml": "4.0.9"
      }
    },
    "node_modules/@types/js-yaml": {
      "version": "4.0.9",
      "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz",
      "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-types-js-yaml-types",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "dependencies": {
    "@types/js-yaml": "4.0.9"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @types/js-yaml.types in pkg:npm/%40types/js-yaml@4.0.9",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40types/js-yaml@4.0.9"
  ],
  "symbols": [
    "@types/js-yaml.types"
  ]
}

import fs from 'node:fs';
import path from 'node:path';

/**
 * Resolves paths to @types/js-yaml package files.
 * @param {string} rootDir Project root directory
 * @returns {{ pkgJsonPath: string, dtsPath: string, dmtsPath: string }}
 */
export function resolveTypePaths(rootDir) {
  const pkgDir = path.join(rootDir, 'node_modules', '@types', 'js-yaml');
  return {
    pkgJsonPath: path.join(pkgDir, 'package.json'),
    dtsPath: path.join(pkgDir, 'index.d.ts'),
    dmtsPath: path.join(pkgDir, 'index.d.mts')
  };
}

/**
 * Loads and parses the @types/js-yaml package manifest.
 * @param {string} pkgJsonPath
 * @returns {object}
 */
export function readPackageManifest(pkgJsonPath) {
  return JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
}

/**
 * Reads declaration file content.
 * @param {string} filePath
 * @returns {string}
 */
export function readDeclarationFile(filePath) {
  return fs.readFileSync(filePath, 'utf8');
}

/**
 * Inspects type definitions and declarations in @types/js-yaml.
 * @param {string} dtsContent
 * @returns {object}
 */
export function inspectDeclarations(dtsContent) {
  return {
    hasGlobalNamespace: dtsContent.includes('export as namespace jsyaml;'),
    hasLoadFunction: dtsContent.includes('export function load(str: string, opts?: LoadOptions): unknown;'),
    hasLoadAllOverload1: dtsContent.includes('export function loadAll(str: string, iterator?: null, opts?: LoadOptions): unknown[];'),
    hasLoadAllOverload2: dtsContent.includes('export function loadAll(str: string, iterator: (doc: unknown) => void, opts?: LoadOptions): void;'),
    hasDumpFunction: dtsContent.includes('export function dump(obj: any, opts?: DumpOptions): string;'),
    hasTypeClass: dtsContent.includes('export class Type {'),
    hasSchemaClass: dtsContent.includes('export class Schema {'),
    hasYAMLExceptionClass: dtsContent.includes('export class YAMLException extends Error {'),
    hasLoadOptionsInterface: dtsContent.includes('export interface LoadOptions {'),
    hasDumpOptionsInterface: dtsContent.includes('export interface DumpOptions {'),
    hasTypeConstructorOptionsInterface: dtsContent.includes('export interface TypeConstructorOptions {'),
    hasSchemaDefinitionInterface: dtsContent.includes('export interface SchemaDefinition {'),
    hasStateInterface: dtsContent.includes('export interface State {'),
    hasMarkInterface: dtsContent.includes('export interface Mark {'),
    hasEventTypeUnion: dtsContent.includes('export type EventType = "open" | "close";'),
    hasFailsafeSchema: dtsContent.includes('export let FAILSAFE_SCHEMA: Schema;'),
    hasJsonSchema: dtsContent.includes('export let JSON_SCHEMA: Schema;'),
    hasCoreSchema: dtsContent.includes('export let CORE_SCHEMA: Schema;'),
    hasDefaultSchema: dtsContent.includes('export let DEFAULT_SCHEMA: Schema;')
  };
}

import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import {
  resolveTypePaths,
  readPackageManifest,
  readDeclarationFile,
  inspectDeclarations
} from '../src/index.mjs';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const rootDir = path.resolve(__dirname, '..');

const { pkgJsonPath, dtsPath, dmtsPath } = resolveTypePaths(rootDir);

assert.ok(fs.existsSync(pkgJsonPath), '@types/js-yaml package.json must exist');
assert.ok(fs.existsSync(dtsPath), '@types/js-yaml index.d.ts must exist');
assert.ok(fs.existsSync(dmtsPath), '@types/js-yaml index.d.mts must exist');

const manifest = readPackageManifest(pkgJsonPath);
const dtsContent = readDeclarationFile(dtsPath);
const dmtsContent = readDeclarationFile(dmtsPath);
const inspection = inspectDeclarations(dtsContent);

// Contract 1: package.json defines types entry point index.d.ts and conditional exports mapping default and import types
{
  assert.equal(manifest.name, '@types/js-yaml', 'package name must match @types/js-yaml');
  assert.equal(manifest.version, '4.0.9', 'package version must match 4.0.9');
  assert.equal(manifest.types, 'index.d.ts', 'manifest types field must point to index.d.ts');
  assert.ok(manifest.exports && manifest.exports['.'], "manifest must configure exports['.']");
  assert.equal(manifest.exports['.'].types.default, './index.d.ts', "exports['.'].types.default must be './index.d.ts'");
  assert.equal(manifest.exports['.'].types.import, './index.d.mts', "exports['.'].types.import must be './index.d.mts'");
}

// Contract 2: The referenced index.d.ts declaration file exists and defines core TypeScript function declarations load, loadAll, and dump
{
  assert.equal(inspection.hasGlobalNamespace, true, 'index.d.ts must declare global jsyaml namespace');
  assert.equal(inspection.hasLoadFunction, true, 'index.d.ts must declare load function signature');
  assert.equal(inspection.hasLoadAllOverload1, true, 'index.d.ts must declare loadAll overload returning unknown[]');
  assert.equal(inspection.hasLoadAllOverload2, true, 'index.d.ts must declare loadAll overload with document iterator callback');
  assert.equal(inspection.hasDumpFunction, true, 'index.d.ts must declare dump function signature');
}

// Contract 3: index.d.ts defines option interfaces LoadOptions, DumpOptions, TypeConstructorOptions, and SchemaDefinition
{
  assert.equal(inspection.hasLoadOptionsInterface, true, 'index.d.ts must declare LoadOptions interface');
  assert.equal(inspection.hasDumpOptionsInterface, true, 'index.d.ts must declare DumpOptions interface');
  assert.equal(inspection.hasTypeConstructorOptionsInterface, true, 'index.d.ts must declare TypeConstructorOptions interface');
  assert.equal(inspection.hasSchemaDefinitionInterface, true, 'index.d.ts must declare SchemaDefinition interface');
  assert.ok(dtsContent.includes('filename?: string | undefined;'), 'LoadOptions must include filename option');
  assert.ok(dtsContent.includes('indent?: number | undefined;'), 'DumpOptions must include indent option');
  assert.ok(dtsContent.includes('sortKeys?: boolean | ((a: any, b: any) => number) | undefined;'), 'DumpOptions must include sortKeys option');
}

// Contract 4: index.d.ts defines classes Type, Schema, and YAMLException with Mark and State interfaces
{
  assert.equal(inspection.hasTypeClass, true, 'index.d.ts must declare Type class');
  assert.equal(inspection.hasSchemaClass, true, 'index.d.ts must declare Schema class');
  assert.equal(inspection.hasYAMLExceptionClass, true, 'index.d.ts must declare YAMLException class extending Error');
  assert.equal(inspection.hasStateInterface, true, 'index.d.ts must declare State interface');
  assert.equal(inspection.hasMarkInterface, true, 'index.d.ts must declare Mark interface');
  assert.equal(inspection.hasEventTypeUnion, true, 'index.d.ts must declare EventType type union');
}

// Contract 5: index.d.ts defines built-in schema constants FAILSAFE_SCHEMA, JSON_SCHEMA, CORE_SCHEMA, and DEFAULT_SCHEMA
{
  assert.equal(inspection.hasFailsafeSchema, true, 'index.d.ts must export FAILSAFE_SCHEMA constant');
  assert.equal(inspection.hasJsonSchema, true, 'index.d.ts must export JSON_SCHEMA constant');
  assert.equal(inspection.hasCoreSchema, true, 'index.d.ts must export CORE_SCHEMA constant');
  assert.equal(inspection.hasDefaultSchema, true, 'index.d.ts must export DEFAULT_SCHEMA constant');
}

// Contract 6: index.d.mts exists and provides ESM wildcard and default type re-exports from index.js
{
  assert.ok(dmtsContent.includes('export * from "./index.js";'), 'index.d.mts must include wildcard export from ./index.js');
  assert.ok(dmtsContent.includes('export { default } from "./index.js";'), 'index.d.mts must include default export from ./index.js');
}

console.log('Contract tests passed: all 6 contracts verified successfully.');