docs: populate Examples section and add baseline tests for _tools/licenses/licenses

[Planeshifter]

Description

Restore two convention-required artifacts in @stdlib/_tools/licenses/licenses that were missing relative to its sibling packages.

Namespace summary

• Namespace: @stdlib/_tools/licenses
• Members analyzed: 11 (header, header-regexp, header-regexp-table, infer, insert-header, insert-header-file-list, licenses, remove-header, remove-header-file-list, update-header, update-header-file-list)
• Features analyzed: file tree, package.json shape, README section list, manifest.json, test/example/benchmark file naming, public signature, return kind, validation prologue, error construction, JSDoc shape, source-level @stdlib/* dependencies
• Features with a clear majority (≥75%) and at least one outlier: presence of test/test.js (9/11), populated ## Examples README section (9/11), errorConstruction === 'format' (9/11)
• Features without a clear majority (excluded from drift analysis): presence of bin field / bin/cli artifacts (7/11), __stdlib__ and os package.json fields (6/11), presence of ## CLI (7/11) and ## Notes (6/11) README sections, returnKind (6/11 value vs 5/11 void), publicSignature and validationPrologue (highly variable across packages with intentionally different APIs)

_tools/licenses/licenses

The <section class="examples"> wrapper in README.md was scaffolded but its heading and code block were commented out; this PR populates the section with a runnable snippet derived from the existing examples/index.js. The package shipped without a test/ directory at all; this PR adds test/test.js with a smoke test asserting the main export is a function and a callback-argument validation test exercising the documented TypeError. package.json gains the corresponding "test": "./test" entry under directories. Conformance for both structural features: 9/11 (82%).

Related Issues

No.

Questions

No.

Other

Validation

• Structural extraction. File tree, package.json keys, README section list (case-preserved, h2/h3, in order), manifest.json shape, and naming of files under test/ / examples/ / benchmark/ were collected per package from the working tree.
• Semantic extraction. Per-package agents read lib/main.js, lib/index.js, and (where present) lib/validate.js, returning a fixed JSON schema covering public signature, return kind, validation prologue, error construction, JSDoc shape, and @stdlib/* source dependencies.
• Three-agent drift validation. Each candidate fix was reviewed independently by a semantic-review pass, a cross-reference pass (checking that tests/examples/sibling docs don't rely on the deviation), and a structural-review pass.

Deliberately excluded

• infer has the same two structural drifts (missing test/test.js, unpopulated ## Examples), but infer/lib/main.js is annotated @private (internal-only API). The cross-reference pass returned needs-human on both candidates, so they were dropped pending a maintainer decision on whether the @private annotation should override the namespace convention.
• header-regexp and infer error construction. Flagged as outliers because they don't use format for error construction, but neither file constructs validation errors of its own: header-regexp delegates input validation to licenseHeader (line 50 comment), and infer only propagates errors from glob/readFiles callbacks. The semantic-review pass marked both as intentional deviations.

Checklist

• Read, understood, and followed the contributing guidelines.

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

This PR was authored by Claude Code running an automated cross-package API-drift detection routine over the eleven packages in @stdlib/_tools/licenses. Candidate fixes were generated by majority-vote analysis (75% threshold) and gated through three independent validation passes before any change was applied. The applied changes are mechanical: the README example is the existing examples/index.js rewritten as an inline snippet using the public require path, and the test file follows the minimal sibling pattern (tape('main export is a function', ...)) plus a single validation case for the documented TypeError. Full audit trail — including dropped candidates and rejection reasons — is in the local run report.

---

@stdlib-js/reviewers

---

Generated by Claude Code

[Planeshifter]

/stdlib update-copyright-years