chore: fix JavaScript lint errors

[Amansingh0807]

Resolves #8586

Description

What is the purpose of this pull request?

This pull request:

• Fixes JavaScript lint errors in the JSDoc examples of the insert-header-file-list module that were causing the "Lint JavaScript files" workflow to fail with an ENOENT error.

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

• #8586
  

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Problem

The JSDoc @example code blocks in lib/node_modules/@stdlib/_tools/licenses/insert-header-file-list/lib/index.js referenced a non-existent file path './foo/bar.js'. Since stdlib's custom jsdoc-doctest ESLint rule actually executes JSDoc examples in a VM to verify they work correctly, it attempted to run the insertHeader() function with this non-existent file, resulting in - Error: ENOENT: no such file or directory, open '/home/runner/work/stdlib/stdlib/foo/bar.js'

Solution

Updated both JSDoc examples to use realistic, executable code that:

• Created a temporary file from the actual fixture file (examples/fixtures/file.js.txt)
• Run the insertHeader() function on the temporary file
• Properly cleaned up by removing the temporary file

This pattern now matches the working example already present in examples/index.js and ensures the jsdoc-doctest rule can execute successfully without errors.

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

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

---

@stdlib-js/reviewers

[stdlib-bot]

Hello! Thank you for your contribution to stdlib.

We noticed that the contributing guidelines acknowledgment is missing from your pull request. Here's what you need to do:

1. Please read our contributing guidelines.

2. Update your pull request description to include this checked box:

   - [x] Read, understood, and followed the [contributing guidelines](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md)

This acknowledgment confirms that you've read the guidelines, which include:

• The developer's certificate of origin
• Your agreement to license your contributions under the project's terms

We can't review or accept contributions without this acknowledgment.

Thank you for your understanding and cooperation. We look forward to reviewing your contribution!

[kgryte]

Thanks for working on this, @Amansingh0807.

I think my main concern with the proposed changes is that we assume that the examples work correctly and we don't need to perform any clean-up. E.g., after creating a temporary file, we could encounter an error before unlinking, resulting in the temporary file hanging around and potentially getting committed.

Alternatively, we could use @stdlib/os/tmpdir to write to the host's temporary directory.

We're also making certain assumptions about this particular file's location relative to the examples directory. E.g., suppose we were to reorganize the examples folder and move the fixtures folder somewhere else. How would a developer know that they inadvertently broke examples in the lib folder? The answer is that they probably wouldn't.

So in short, in their current form, I don't think we can accept the proposed changes. I suggest reworking the examples to be more robust.

[Amansingh0807]

Thanks for working on this, @Amansingh0807.

I think my main concern with the proposed changes is that we assume that the examples work correctly and we don't need to perform any clean-up. E.g., after creating a temporary file, we could encounter an error before unlinking, resulting in the temporary file hanging around and potentially getting committed.

Alternatively, we could use @stdlib/os/tmpdir to write to the host's temporary directory.

We're also making certain assumptions about this particular file's location relative to the examples directory. E.g., suppose we were to reorganize the examples folder and move the fixtures folder somewhere else. How would a developer know that they inadvertently broke examples in the lib folder? The answer is that they probably wouldn't.

So in short, in their current form, I don't think we can accept the proposed changes. I suggest reworking the examples to be more robust.

Thank you for the detailed feedback, @kgryte! I've updated the examples to address your concerns:

Changes:

• Using @stdlib/os/tmpdir for system temp directory instead of project directory
• Removed path dependencies (no __dirname or fixture folder assumptions)
• Improved cleanup to always run, even on errors
• Examples now self-contained with inline content

Please let me know if any further adjustments are needed.
Thanks again for your guidance!

[Planeshifter]

Thanks for addressing the feedback!

[kgryte]

@Planeshifter I am not actually convinced these changes are necessary.

[kgryte]

The examples could simply be updated such that, instead of throwing, we do console.error( error.message ), which is something we do in other examples.

[kgryte]

As the examples for this tool are meant to be illustrative, IMO creating temporary files and cleaning up seems like overkill.

[Planeshifter]

@kgryte Yeah, that's fair. So let's instead move away from throwing errors in such example code involving files and instead use the console.error pattern. I took a first stab at this in cb4ee92. Given that this resolves the lint error, I am going to close this PR.

Thank you @Amansingh0807 for your efforts and contributions to stdlib; they are much appreciated, even in case they may not always end up landing in the casebase!