docs: add negative-scale @example to stats/base/dists/lognormal/cdf

[Planeshifter]

Description

What is the purpose of this pull request?

This pull request:

• adds the canonical // Negative scale parameter: @example block to the JSDoc in lib/main.js and to the interface CDF main signature JSDoc in docs/types/index.d.ts for @stdlib/stats/base/dists/lognormal/cdf, bringing the package's JSDoc and TypeScript declarations into conformance with the four sibling (x|p, mu, sigma) lognormal packages.

Namespace summary

• Target: @stdlib/stats/base/dists/lognormal
• Members analyzed: 14 (cdf, ctor, entropy, kurtosis, logcdf, logpdf, mean, median, mode, pdf, quantile, skewness, stdev, variance)
• Features analyzed: file tree, package.json top-level / scripts / directories / keywords keys, README section sequence, manifest.json shape, test/benchmark/examples filenames, public signature, return kind, validation prologue, error construction, JSDoc shape (param tags / returns / throws / @example blocks), lib/main.js require dependencies.
• Features with clear majority (≥75%): package.json top-level key set (100%); directories keys benchmark/doc/example/lib/test (100%); README sections ## Usage and ## Examples (100%); 11/14 = 79% conformance on the canonical isnan(mu) || isnan(sigma) || sigma <= 0.0 validation prologue; 13/14 = 93% on errorConstruction = "none"; 14/14 on returnKind = "value"; 14/14 on jsdocShape.hasExample; 4/5 = 80% on the // Negative scale parameter: @example block in lib/main.js JSDoc and docs/types/index.d.ts interface JSDoc among (x|p, mu, sigma) packages.
• Features without clear majority (excluded from drift detection): native-bindings file group (manifest.json, binding.gyp, include.gypi, src/**, lib/native.js, benchmark/c/**, benchmark/benchmark.native.js, examples/c/**, test/test.native.js) and ## C APIs README section at 10/14 = 71%; gypfile package.json key at 10/14 = 71%; keywords array contents (varies by function semantics); public signature shape (split (mu, sigma) / (x, mu, sigma) / (p, mu, sigma) / (mu?, sigma?) constructor — no shape ≥75%); test fixture style (Julia vs R, data.json vs *_location.json/*_mean.json).

stats/base/dists/lognormal/cdf

Adds a // Negative scale parameter: @example block to the JSDoc in lib/main.js and to the interface CDF signature in docs/types/index.d.ts, documenting that cdf( 2.0, 0.0, -1.0 ) returns NaN. The case is already covered by the sigma <= 0.0 guard, the README.md, and docs/repl.txt — the omission was a JSDoc/TypeScript oversight, not intentional. Brings cdf into conformance with the four sibling lognormal packages (pdf, logpdf, logcdf, quantile) that already carry this block.

Validation

Checked:

• structural feature extraction (file tree, package.json shape, README section list, manifest.json shape, test/benchmark/example filenames) across all 14 members.
• semantic feature extraction (public signature, validation prologue, error construction, JSDoc shape, dependency set) across all 14 members via per-package sonnet agents reading lib/main.js, lib/index.js, lib/factory.js, and lib/validate.js directly.
• three-agent drift validation on the single surviving correction:
  • opus semantic-review confirmed the missing @example block is unintentional drift, given identical sigma <= 0.0 validation and existing README/REPL coverage of the same case.
  • opus cross-reference confirmed test/test.cdf.js already covers cdf( x, mu, -1.0 ) === NaN (lines 75–79), no test or example inspects JSDoc text, and no sibling-package documentation references would be affected.
  • sonnet structural-review confirmed the addition mirrors the canonical pattern in pdf, logpdf, logcdf, and quantile, and that placement in both lib/main.js and the interface CDF main-signature JSDoc is correct.

Deliberately excluded:

• ctor errorConstruction = "format" and validationPrologue using isPositive/isNumber (vs. the isnan || ... || sigma <= 0.0 majority). Intentional deviation: a class constructor legitimately throws TypeError on bad arguments rather than returning NaN; semantic shape is genuinely different.
• logcdf JSDoc types sigma as NonNegativeNumber (vs. 13/14 PositiveNumber) and lacks the canonical validation prologue. Intentional deviation: the function delegates to @stdlib/stats/base/dists/normal/logcdf after ln(x) transformation, which handles sigma === 0 as a degenerate distribution returning -Infinity (documented in the JSDoc and repl.txt); narrowing to PositiveNumber would misrepresent supported behavior.
• stdev lacks the canonical validation prologue, delegating return sqrt( variance( mu, sigma ) );. Intentional deviation: variance already performs identical validation; sqrt(NaN) === NaN preserves observable behavior; binomial/stdev, poisson/stdev, pareto-type1/stdev follow the same delegating idiom.
• Native-bindings file group at 10/14 = 71% — below the 75% threshold and excluded from drift detection. The four packages without native bindings (cdf, ctor, logcdf, logpdf) reflect a deliberate JS-only subset, not drift; adding C bindings is a substantive new feature handled in separate PRs (e.g. feat: add C implementation for stats/base/dists/lognormal/cdf #10883, feat: add C implementation for stats/base/dists/lognormal/cdf #10809, feat: add C implementation for stats/base/dists/lognormal/logcdf #10882).
• Test fixture filename drift (cdf uses negative_mean.json/positive_mean.json; pdf/quantile/logpdf use negative_location.json/positive_location.json; logcdf uses R fixtures rather than Julia). Cascading change: would require regenerating fixture data and editing runner.jl/runner.R; out of scope for mechanical drift correction.
• ## See Also README section drift — auto-populated by the package generator; gate 7a excludes.
• Dependency-set drift across packages — varies legitimately by mathematical implementation.

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.

Random namespace pick from the lib/node_modules/@stdlib/ walk of directories with ≥8 direct child packages. Does not conflict with the open native-binding PRs targeting the same package (#10883, #10809), which touch only lib/native.js, src/**, binding.gyp, manifest.json, include.gypi, benchmark/benchmark.native.js, test/test.native.js, and the ## C APIs README section — orthogonal to the JSDoc and TypeScript-declaration files modified here.

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 authored by Claude Code via the cross-package drift-detection routine: structural and semantic features were extracted from every member of stats/base/dists/lognormal, majority patterns were computed at a 75% conformance threshold, and three independent validation agents (opus semantic-review, opus cross-reference, sonnet structural-review) confirmed the surviving correction was high-signal mechanical drift before any file was edited. The single edit is purely additive JSDoc + TypeScript-declaration documentation; no source, test, or behavioral changes.

---

@stdlib-js/reviewers

---

Generated by Claude Code

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
stats/base/dists/lognormal/cdf	$\color{green}217/217$ $\color{green}+100.00%$	$\color{green}21/21$ $\color{green}+100.00%$	$\color{green}3/3$ $\color{green}+100.00%$	$\color{green}217/217$ $\color{green}+100.00%$

The above coverage report was generated for the changes in this PR.