Skip to main content

Require JSDoc Since

Require a @since tag in every JSDoc block and validate its value so every declaration records the version it was introduced in.

Summary

  • Reports any JSDoc block on a class, method, property, function, type alias, interface, or enum that is missing a @since tag.
  • Also validates the value of @since — and of @deprecated when present — rejecting empty values, malformed strings, and versions that exceed the package's current version.
  • Accepts the UNRELEASED sentinel (optionally followed by trailing prose) for new or newly deprecated declarations that haven't shipped yet.
  • Accepts a concrete semver X.Y.Z (with optional trailing prose such as 0.15.0 backported) as long as the version is less than or equal to the nearest package.json version.

Why Use This Rule?

  1. Provides a version history directly in source code so contributors know when each declaration was added.
  2. Prevents accidental hand-written future versions (e.g., @since 99.0.0) from slipping through a review unnoticed.
  3. Enforces the UNRELEASED sentinel workflow so real versions are stamped at release by nova utility changelog --release, not guessed by hand.
  4. Makes it possible to generate changelogs and migration guides from @since tags.

Examples

Configuration

Options

warning

ignoreFiles is an escape hatch for files where this rule genuinely does not apply. It is not intended for routine use.

OptionTypeDefaultDescription
ignoreFilesstring[][]File names to skip. Supports a leading-* suffix (*.test.ts), an exact path, or a trailing path segment; ** globs are not supported.

Messages

Three message IDs are reported by this rule, each covering a distinct failure:

  • requireSinceTag — The JSDoc block has no @since tag at all. Add @since UNRELEASED for a new declaration.
  • invalidSinceVersion — The @since tag is present but its value is empty, malformed, or a version greater than the current package.json version. Use UNRELEASED or a valid semver that is less than or equal to the current version.
  • invalidDeprecatedVersion — A @deprecated tag is present but its version value is malformed or greater than the current package.json version. Use UNRELEASED for a newly deprecated member or a valid semver at or below the current version.

Autofix

Autofix is not available for this rule. Flagged code must be updated manually.

For new or newly deprecated declarations, the correct value is the literal UNRELEASED. The real version is stamped automatically when you run nova utility changelog --release at release time.

Troubleshooting

  • Rule fires on declarations without JSDoc — The rule only checks declarations that already have a JSDoc block. If a declaration has no JSDoc comment at all, the rule does not report it.
  • Checked node types — The rule checks classes, methods, properties, function declarations, type aliases, interfaces, and enums. Function expressions and arrow functions assigned to variables (const foo = () => {}) are not checked, nor are variable declarations.
  • Value validation is skipped when no versioned package.json is found, or when the package version is 0.0.0 — The rule walks up the directory tree to find the nearest package.json that has a version field. If none is found, or the version is 0.0.0 (an unreleased package that is never published), version-range validation is skipped and only the presence of @since is enforced. This allows internal apps to carry @since tags that track the library's version rather than their own 0.0.0 version.
  • Trailing prose after the version is allowed — Values like 0.15.0 backported are accepted. The rule extracts the leading semver and compares it against the package version; anything after the first whitespace is treated as descriptive text.