microsoft/definitelytyped-tools

The @definitelytyped/definitions-parser package is responsible for processing the DefinitelyTyped repository to provide structured data about TypeScript definitions. Its core responsibilities include:

1. Repository Acquisition: Downloading a copy of the DefinitelyTyped repository from GitHub (or using a local copy).
2. Data Extraction & Analysis: Reading all definitions from the repository, performing analysis, and caching the resulting data in a data directory.
3. Programmatic Access: Providing an API wrapper to interact with the analyzed and cached definition data.

DefinitelyTyped-tools is a monorepo containing various utilities for managing and validating DefinitelyTyped (DT) packages. Key packages include:

• definitions-parser: Reads DefinitelyTyped repository data.
• dtslint: Tests TypeScript declaration files for style and correctness.
• dtslint-runner: Runs dtslint across all or specific packages on DT.
• eslint-plugin: Provides DT-specific linting rules.
• dts-critic: Detects mismatches between type packages and their original JavaScript packages.
• header-parser: Extracts and checks DT-related information from package.json.
• publisher: Handles the publishing workflow (part of types-publisher).
• retag: Adds ATA tags to @types packages.
• typescript-versions: Tracks TypeScript versions published to npm and supported on DT.
• utils: Shared utilities used across the monorepo.

The checks performed by dts-critic depend on whether the declaration is for an npm package or a non-npm package (defined by having a Definitely Typed-conforming package.json with "nonNpm": true).

npm declarations

1. An npm package with the same name as the declaration must exist.
2. If a Definitely Typed-conforming package.json is present, the npm package's version must match the declaration's version.
3. In code mode, the declaration must match the source JavaScript module.

non-npm declarations

1. An npm package with the same name cannot exist.
2. In code mode, if a path to the JavaScript source file is provided, the declaration must match the source JavaScript module.

The Mergebot automates the workflow for DefinitelyTyped (DT) Pull Requests. It categorizes PRs to determine if they can be merged automatically or if they require manual intervention from a DT maintainer.

Bot Exclusions:

• Draft PRs
• Closed PRs

Manual Review Requirements: Maintainers must review PRs that:

• Affect DT infrastructure or a module's infra (e.g., tsconfig.json).
• Affect more than 50 Definition Owners.
• Affect extremely popular packages (>5m downloads per month).
• Add new packages.
• Change DT types without accompanying tests.
• Change DT types where no other Definition Owners exist.

Blessing System:

• PRs blessed as review (via info.blessingKind) are excluded from automation where possible.
• PRs blessed as merge can be merged without manual reviews.

The --mode flag determines the depth of the validation performed by dts-critic:

• name-only: Validates the package name and the DefinitelyTyped header against existing npm packages. It ensures that if you claim to be a package named cool-js-package, that package actually exists on npm.
• code: Performs all name-only checks plus an additional validation to ensure that the declaration's exports match the source JavaScript module's exports (e.g., verifying that a default export in the .d.ts exists in the .js source).

# Example: Running in code mode with a specific JS source
$ node dist/index.js --dts=path/to/index.d.ts --js=path/to/source.js --mode=code

The bot monitors PRs for staleness across three categories:

1. Unmerged: Ready to merge, but the author/owners haven't requested it.
2. Abandoned: Failing CI or has unresolved change requests.
3. Unreviewed: Has not received any reviews.

Each category follows a configurable timeline. When a PR enters a timeline, it progresses through these states:

• fresh: The initial state after entering the timeline.
• attention: Inactivity is noted in the bot's welcome message.
• nearly: A comment is posted and a staleness category label is added.
• done: The final state. Depending on the category, the PR is either moved to a specific column (for unreviewed) or closed (for unmerged or abandoned).

For the specific day counts and conditions governing these transitions, refer to the getStaleness definition in packages/mergebot/src/compute-pr-actions.ts.

The Mergebot operates in three main stages once it receives a Pull Request (PR) number:

1. Query PR Metadata: Uses pr-info (src/pr-info.ts) to query the GitHub GraphQL API for metadata related to the PR.
2. Compute Actions: Uses compute-pr-actions (src/compute-pr-actions.ts) to create a PR actions metadata object.
3. Execute Actions: Uses execute-pr-actions (src/execute-pr-actions.ts) to perform the actual work based on the computed actions.

In production, an Azure Function in PR-Trigger receives webhooks from the DefinitelyTyped repository and initiates these steps.

To use dts-critic, you must first build the program from source. Once built, you can execute it using node with specific flags to validate a TypeScript declaration file (.d.ts) against its corresponding JavaScript source or an npm package.

If the .d.ts file is named index.d.ts, dts-critic automatically uses the parent directory's name as the package name (e.g., ~/dt/types/jquery/index.d.ts resolves to the package jquery).

# Build the program
$ npm run build

# Run the program
$ node dist/index.js --dts=path-to-d.ts [--js=path-to-source] [--mode=mode] [--debug]