docs: bracket positional dir metavar in _tools/lint/pkg-json and _tools/lint/repl-txt usage strings

[Planeshifter]

Description

What is the purpose of this pull request?

This pull request:

• Aligns the two remaining docs/usage.txt / README.md outliers in @stdlib/_tools/lint/* with the namespace's documented-CLI conventions. No observable CLI behavior changes — the bin/cli prints docs/usage.txt verbatim as --help, and test/test.cli.js reads the same file for its expected value, so both sides of the equality shift together.
• Normalizes the leading indent in the same two files from 9 spaces to 8 spaces (matching sibling pkg-json-names and the [usage.txt] indent_size = 2 rule in the root .editorconfig). This is pre-existing lint debt that surfaced only after the PR touched the files.

Namespace summary

• Namespace: @stdlib/_tools/lint (9 non-autogenerated members: filenames, header-filenames, license-header, license-header-file-list, license-header-glob, namespace-aliases, pkg-json, pkg-json-names, repl-txt).
• Features analyzed: file tree, package.json shape, README section list + order, docs/usage.txt first/last byte and Usage: line shape, etc/cli_opts.json shape, manifest.json presence, test/ / benchmark/ / examples/ filename sets, plus the semantic pass over lib/index.js / lib/main.js / lib/async.js / lib/sync.js / lib/validate.js / lib/lint.js (signature, return kind, validation prologue, error construction, JSDoc shape, @stdlib/* dependencies).
• Clear majority (≥75% conformance): top-level file tree, package.json top-level key set, directories/engines/license/bugs/homepage/repository shape, etc/cli_opts.json boolean/alias block, docs/usage.txt leading newline, docs/usage.txt trailing single newline, angle-bracketed positional metavars in Usage:, format-based thrown-error construction, callback-parameter validation via isFunction, hasExample: true on the primary export.
• No clear majority (excluded): package.json os field (2/9 split — behavior-affecting; already flagged and excluded by PR chore: align outliers in _tools/lint with namespace majority patterns #11835), presence/shape of lib/main.js vs lib/async.js+lib/sync.js (reflects real generation-of-API split across license-header* vs the rest), README <section class="notes"> content (empty sections in pkg-json and repl-txt need authored content, not mechanical alignment), returnsTag and throwsTags sets on the primary JSDoc (heterogeneous — no ≥7/9 pattern).

@stdlib/_tools/lint/pkg-json

Bracketed the positional metavar in the Usage: line of docs/usage.txt and README.md ([dir] → [<dir>]) to match the 78% of _tools/lint siblings that use angle-bracket metavars, and trimmed the trailing blank line from docs/usage.txt so --help output no longer emits a spurious empty line. Follow-up commit reduces the --option indent from 9 to 8 spaces (multiple of 2, per .editorconfig) and drops one space from the -h,/-V, rows so the columns still align — the odd indent tripped the Lint Changed Files editorconfig check as soon as the file entered the PR diff. bin/cli prints docs/usage.txt verbatim and test/test.cli.js compares against the same file, so test expectations are unchanged.

@stdlib/_tools/lint/repl-txt

Bracketed the positional metavar in the Usage: line of docs/usage.txt and README.md to [<dir>], matching 7 of 9 sibling packages in _tools/lint (~78%). Trimmed the trailing blank line from docs/usage.txt so the file ends with a single \n, since the extra newline propagated verbatim into bin/cli --help output. Follow-up commit applies the same indent normalization (9 → 8 spaces on --option lines) as pkg-json for the same editorconfig reason. No test expectation changes: test/test.cli.js reads docs/usage.txt symmetrically.

Validation

Checked:

• Structural extraction over file tree, package.json keys, README section list, docs/usage.txt first/last-byte shape, and Usage: line format across all 9 namespace members.
• Semantic extraction via per-package agents over lib/index.js / lib/main.js / lib/async.js / lib/sync.js / lib/validate.js (public signature, validation prologue, error construction, JSDoc shape, @stdlib/* dependencies).
• Three-agent drift validation (semantic-review, cross-reference, structural-review) — all three returned confirmed-drift for both pkg-json and repl-txt on both the bracket-metavar and trailing-newline corrections. Cross-reference verified that test.cli.js in both packages reads docs/usage.txt at runtime for its expected value and compares symmetrically to stderr, so no test expectation is pinned to the pre-fix bytes; no example loads the usage text.
• Cross-run dedup against merged PRs chore: align outliers in _tools/lint with namespace majority patterns #11835 (2026-04-29) and refactor: normalize error messages and descriptions #12214 (2026-05-20), which touched this namespace previously. Neither addressed the Usage: metavar bracketing nor the docs/usage.txt trailing-newline shape.

Deliberately excluded:

• namespace-aliases missing test/test.sync.js — reraised as a candidate, but PR chore: align outliers in _tools/lint with namespace majority patterns #11835 already surfaced and rejected this with the reason "a meaningful test would require fixtures the package lacks". Not reopened.
• package.json os field divergence — 2/9 vs 7/9, behavior-affecting on publish, unclear intent (already excluded by chore: align outliers in _tools/lint with namespace majority patterns #11835).
• pkg-json and repl-txt empty <section class="notes"> blocks in Usage sections — requires authored content, not mechanical alignment.
• lib/main.js vs lib/async.js+lib/sync.js split — reflects the older license-header* API shape vs the newer async/sync split; changing it is a rewrite, not drift correction.
• license-header returnKind/publicSignature deviation — intentional (synchronous string-blob primitive).
• license-header-file-list publicSignature deviation — intentional (positional file-list is the API contract).
• Odd-indent violation in header-filenames/docs/usage.txt — same 9-space indent, but the file isn't touched by this PR, so it stays out of Lint Changed Files. Log-and-skip; separate maintenance PR appropriate.

Related Issues

Does this pull request have any related issues?

No.

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.

Each package gets two commits (one for the drift correction, one for the indent normalization) so the audit trail stays per-package and per-concern. Conformance percentages for each drift item are quoted in the respective commit body. Total diff is 4 files, 28 insertions and 30 deletions.

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

This PR was produced by an automated cross-package API drift sweep run by Claude Code against the @stdlib/_tools/lint namespace. Structural and semantic features were extracted per package, majorities were computed at the 75% threshold, and each surviving candidate was validated by three independent review passes (semantic, cross-reference, structural) before any file was modified. The follow-up indent-normalization commits were added after Lint Changed Files surfaced a pre-existing editorconfig violation on the two files the PR already touched. All edits are mechanical whitespace or text substitutions in two packages; no behavior, signatures, or test expectations changed.

---

@stdlib-js/reviewers

[Planeshifter]

CI status after the follow-up indent-normalization push (4f8ce7272):

• Lint Changed Files — editorconfig step: fixed. The 9-space --option indent in docs/usage.txt was pre-existing lint debt that only surfaced once the file entered the PR diff; the follow-up commits normalize to 8 spaces (multiple of 2, matching sibling pkg-json-names and the [usage.txt] indent_size = 2 rule in the root .editorconfig).
• Lint Changed Files — lint-markdown-package-readme-files step: still failing with TypeError: Cannot read properties of null (reading 'split') (4 occurrences, then make: *** Error 1). No stack trace is emitted, so I can't pinpoint the origin remotely. The same TypeError appears in Run changed examples, which suggests it's a shared plugin path, not the byte-level content of my diff — the two ASCII edits ([dir] → [<dir>] and one trailing-newline strip) don't obviously interact with .split(':') anywhere in the stdlib remark plugins (the only .split(':') in _tools/remark/plugins/** is in remark-run-javascript-examples/lib/parse_config.js:73, which reads code-block config comments — my READMEs don't add or change those).

My working hypothesis is that this is pre-existing infrastructure noise on _tools/lint/*/README.md specifically: the READMEs' javascript example blocks are lint( done ) calls that scan the CI's full stdlib checkout, producing large output that eventually trips a downstream plugin. Prior drift-sweep PRs in this namespace (#11835, #12214) didn't touch a README, so this path hadn't been exercised recently — I don't have a prior successful run to compare against.

Options:

1. Merge the drift + indent normalization as-is and treat the TypeError as pre-existing infrastructure debt tracked separately.
2. Revert the docs/usage.txt changes and land only the README.md bracket change (which would introduce a small README ↔ --help cosmetic mismatch).
3. Close this PR and drop both drift corrections; log both pkg-json and repl-txt in the drift report as blocked by the lint-markdown-package-readme-files failure.

Happy to take any of the three. Local drift report and per-feature majority breakdown are at ~/drift-reports/drift-tools-lint-2026-07-08.md on my run environment; can paste it into the PR body if useful.

---

Generated by Claude Code