From 71b5a310a23bafd15a2be5dd3f7c180c824342b9 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 26 Nov 2025 13:00:04 +0000
Subject: [PATCH 1/2] Initial plan


From c2e22d6f31cdc4d3c241d98c8e42116e8799d498 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 26 Nov 2025 13:11:22 +0000
Subject: [PATCH 2/2] Add proper JSDoc @deprecated annotations for re-exports

Replace simple `// DEPRECATED - use original` comments with proper JSDoc
@deprecated tags. The annotations clearly indicate that:
1. The re-export location is deprecated (not the class/type itself)
2. Users should import from the new Contrib namespace instead
3. The exported classes/types themselves are NOT deprecated

This makes deprecation visible in IDEs and documentation tools.

Co-authored-by: jkowalleck <2765863+jkowalleck@users.noreply.github.com>
---
 src/builders/index.node.ts    |  7 ++++++-
 src/factories/index.common.ts | 14 ++++++++++++--
 src/factories/index.node.ts   |  7 ++++++-
 src/types/index.ts            |  7 ++++++-
 src/utils/index.node.ts       | 14 ++++++++++++--
 5 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/src/builders/index.node.ts b/src/builders/index.node.ts
index d5bd7c2e8..fe9bc9578 100644
--- a/src/builders/index.node.ts
+++ b/src/builders/index.node.ts
@@ -17,4 +17,9 @@ SPDX-License-Identifier: Apache-2.0
 Copyright (c) OWASP Foundation. All Rights Reserved.
 */
 
-export * as FromNodePackageJson from '../contrib/fromNodePackageJson.node/builders' // DEPRECATED - use original
+/**
+ * @deprecated This re-export location is deprecated.
+ * Import from `Contrib.FromNodePackageJson.Builders` instead.
+ * The exported classes themselves are NOT deprecated - only this import path.
+ */
+export * as FromNodePackageJson from '../contrib/fromNodePackageJson.node/builders'
diff --git a/src/factories/index.common.ts b/src/factories/index.common.ts
index 5d776cd25..57fb6ef02 100644
--- a/src/factories/index.common.ts
+++ b/src/factories/index.common.ts
@@ -19,5 +19,15 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
 
 // not everything is public, yet
 
-export * from '../contrib/license/factories' // DEPRECATED - use original
-export * from '../contrib/packageUrl/factories' // DEPRECATED - use original
+/**
+ * @deprecated This re-export location is deprecated.
+ * Import from `Contrib.License.Factories` instead.
+ * The exported classes themselves are NOT deprecated - only this import path.
+ */
+export * from '../contrib/license/factories'
+/**
+ * @deprecated This re-export location is deprecated.
+ * Import from `Contrib.PackageUrl.Factories` instead.
+ * The exported classes themselves are NOT deprecated - only this import path.
+ */
+export * from '../contrib/packageUrl/factories'
diff --git a/src/factories/index.node.ts b/src/factories/index.node.ts
index f37d32d58..7e0f6b75f 100644
--- a/src/factories/index.node.ts
+++ b/src/factories/index.node.ts
@@ -21,6 +21,11 @@ export * from './index.common'
 
 // region node-specifics
 
-export * as FromNodePackageJson from '../contrib/fromNodePackageJson.node/factories' // DEPRECATED - use original
+/**
+ * @deprecated This re-export location is deprecated.
+ * Import from `Contrib.FromNodePackageJson.Factories` instead.
+ * The exported classes themselves are NOT deprecated - only this import path.
+ */
+export * as FromNodePackageJson from '../contrib/fromNodePackageJson.node/factories'
 
 // endregion node-specifics
diff --git a/src/types/index.ts b/src/types/index.ts
index 734995475..1998c3d49 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -23,4 +23,9 @@ export * from './integer'
 export * from './mimeType'
 
 // yes, this is node-specific, but who cares - these are just types
-export * from '../contrib/fromNodePackageJson.node/types' // DEPRECATED - use original
+/**
+ * @deprecated This re-export location is deprecated.
+ * Import from `Contrib.FromNodePackageJson.Types` instead.
+ * The exported types themselves are NOT deprecated - only this import path.
+ */
+export * from '../contrib/fromNodePackageJson.node/types'
diff --git a/src/utils/index.node.ts b/src/utils/index.node.ts
index 8e04417e8..a384c8832 100644
--- a/src/utils/index.node.ts
+++ b/src/utils/index.node.ts
@@ -21,7 +21,17 @@ export * from './index.common'
 
 // region node-specifics
 
-export * as NpmjsUtility from '../contrib/fromNodePackageJson.node/utils' // DEPRECATED - use original
-export * as LicenseUtility from '../contrib/license/utils.node' // DEPRECATED - use original
+/**
+ * @deprecated This re-export location is deprecated.
+ * Import from `Contrib.FromNodePackageJson.Utils` instead.
+ * The exported utilities themselves are NOT deprecated - only this import path.
+ */
+export * as NpmjsUtility from '../contrib/fromNodePackageJson.node/utils'
+/**
+ * @deprecated This re-export location is deprecated.
+ * Import from `Contrib.License.Utils` instead.
+ * The exported utilities themselves are NOT deprecated - only this import path.
+ */
+export * as LicenseUtility from '../contrib/license/utils.node'
 
 // endregion node-specifics