Description

What is the purpose of this pull request?

This pull request introduces a prototype for a C source doctest runner.

The goal of this draft PR is to demonstrate and validate the approach for:

• extracting examples from C source files
• generating corresponding test programs

• executing examples and validating // returns annotations, providing exact source line reporting for mismatches along with suggested corrected annotation values

This is an experimental proof-of-concept, intended primarily for reviewers to:

• inspect the scripts
• understand the proposed workflow
• evaluate the feasibility of the approach

Usage

You can clone this PR and try the prototype:

• Run doctest for a single file:
  make doctest-c-files FILES="path/to/file.c"

• Run doctest for multiple files using a filter:
  make doctest-c SOURCES_FILTER='.*/stats/base/dists/weibull/pdf/.*'

• Run doctest for all C files in the repository:
  make doctest-c

Note: A full repository-wide run currently takes ~25–30 minutes.

Notes

• Files containing placeholder ellipsis (...) are currently skipped, as they are illustrative examples and not meant for execution.
• Files involving N-API are also skipped for now. If needed, execution support for these can be introduced later.
• In the future, support for ignore flags will be added to selectively exclude files from doctesting.

Related Issues

Does this pull request have any related issues?

No.

Questions

Any questions for reviewers of this pull request?

• Any suggestions on improving structure or design before moving toward a full implementation?

Other

Any other information relevant to this pull request?

This PR is intentionally marked as a draft and is not a final implementation.
The focus is on validating the idea and gathering early feedback before refining further.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• No

Disclosure

N/A

@stdlib-js/reviewers