From 790e4f886a8b89a8b45277ca94a14c6afe0132ab Mon Sep 17 00:00:00 2001 From: Omotola Akeredolu Date: Wed, 14 Jun 2023 15:37:35 -0700 Subject: [PATCH 1/4] Npm documentation --- docs/detectors/README.md | 2 +- docs/detectors/npm.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) create mode 100644 docs/detectors/npm.md diff --git a/docs/detectors/README.md b/docs/detectors/README.md index 34012c2e3..75dff296f 100644 --- a/docs/detectors/README.md +++ b/docs/detectors/README.md @@ -5,7 +5,7 @@ - [Gradle](gradle.md) - [Linux](linux.md) - [Maven](maven.md) -- NPM +- [NPM](npm.md) - NuGet - [Pip](pip.md) - [Poetry](poetry.md) diff --git a/docs/detectors/npm.md b/docs/detectors/npm.md new file mode 100644 index 000000000..e952e7909 --- /dev/null +++ b/docs/detectors/npm.md @@ -0,0 +1,15 @@ +# Npm Detection + +## Requirements + + There are multiple detectors that make up npm detection and each detector searches for the following files: + - [The Npm Component detector looks for `package.json`](https://github.com/microsoft/component-detection/blob/251276d7951c7eaa880ed58b1a974b25dba92cd2/src/Microsoft.ComponentDetection.Detectors/npm/NpmComponentDetector.cs#L36) + - [The NpmLockFile detector looks for `package-lock.json`, `npm-shrinkwrap.json`,`lerna.json`](https://github.com/microsoft/component-detection/blob/251276d7951c7eaa880ed58b1a974b25dba92cd2/src/Microsoft.ComponentDetection.Detectors/npm/NpmLockfileDetectorBase.cs#L52) + +## Detection strategy + Npm detection searches for dependencies in `packages.json`, `package-lock.json`, `npm-shrinkwrap.json`(which are autogenerated by running npm init and other commands) as well as `lerna.json` in the scan directory. The lockfile detector is able to scan for transitive dependencies within the project. There is also an extension of the lockfile detector the NpmLockFilev3 detector that is able to scan [version 3 of lockfiles](https://github.com/microsoft/component-detection/blob/251276d7951c7eaa880ed58b1a974b25dba92cd2/src/Microsoft.ComponentDetection.Detectors/npm/NpmLockfile3Detector.cs#L36) + + +## Known limitations +Npm has the option to download optional dependencies which can cause an overreporting issue with the detector. However this is not much of an issue currently since most projects only use dependencies and devdependencies. + From f3d7d0811a6c4e7df8ddadfac1691b739c3ca93b Mon Sep 17 00:00:00 2001 From: Omotola Akeredolu Date: Fri, 16 Jun 2023 09:43:06 -0700 Subject: [PATCH 2/4] Added status of each detector --- docs/detectors/README.md | 98 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/docs/detectors/README.md b/docs/detectors/README.md index 75dff296f..3f5c5c742 100644 --- a/docs/detectors/README.md +++ b/docs/detectors/README.md @@ -1,13 +1,111 @@ # Detectors - CocoaPods + +| Detector| Status | +|-------|---------| +|PodComponentDetector | Stable | + +- DockerFile + +| Detector| Status | +|-------|---------| +|DockerFileDetector | DefaultOff | + - [Go](go.md) + +| Detector| Status | +|-------|---------| +|GoComponentDetector | Stable | + - [Gradle](gradle.md) + +| Detector| Status | +|-------|---------| +|GradleComponentDetector | Stable | + +- Ivy + +| Detector| Status | +|-------|---------| +|IvyDetector | Experimental | + - [Linux](linux.md) + +| Detector| Status | +|-------|---------| +|LinuxContainerDetector | Stable | + - [Maven](maven.md) + +| Detector| Status | +|-------|---------| +|MavenCliComponentDetector | Stable | + - [NPM](npm.md) + +| Detector| Status | +|-------|---------| +|NpmComponentDetector | Stable | +|NpmLockFileDetector | Stable | +|NpmLockFile3Detector | Experimental | + - NuGet + +| Detector| Status | +|-------|---------| +|NugetComponentDetector | Stable | +|NugetPackagesConfigDetector | Stable | +|NuGetProjectModelProjectCentricComponentDetector | Stable | + - [Pip](pip.md) + +| Detector| Status | +|-------|---------| +|PipComponentDetector | Stable | + + +- Pnpm + +| Detector| Status | +|-------|---------| +|PnpmComponentDetector | Stable | + + - [Poetry](poetry.md) + +| Detector| Status | +|-------|---------| +|PoetryComponentDetector | Experimental | + - Ruby + +| Detector| Status | +|-------|---------| +|RubyComponentDetector | Stable | + - Rust + +| Detector| Status | +|-------|---------| +|RustCrateDetector | Stable | + +- Spdx + +| Detector| Status | +|-------|---------| +|Spdx22ComponentDetector | DefaultOff | + + +- Vcpkg + +| Detector| Status | +|-------|---------| +|VcpkgComponentDetector | Experimental | + + +- Yarn + +| Detector| Status | +|-------|---------| +|YarnLockDetector | Stable | \ No newline at end of file From 11f1656bd03b07be201a99e6d3e9c9cd1e5b2f4d Mon Sep 17 00:00:00 2001 From: Omotola Akeredolu Date: Fri, 16 Jun 2023 10:41:17 -0700 Subject: [PATCH 3/4] Added status link to main readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5b129da11..6dafd88b1 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ Detectors have 3 levels of "stability": * `Experimental` * `Stable` -DefaultOff detectors need to be explicitly enabled to run and produce a final graph output. Experimental detectors run by default but **will not** produce a final graph output. Stable detectors run and produce a final graph output by default. Here is how you can [enable default off/experimental](./docs/enable-default-off.md) detectors. +DefaultOff detectors need to be explicitly enabled to run and produce a final graph output. Experimental detectors run by default but **will not** produce a final graph output. Stable detectors run and produce a final graph output by default. Here is how you can [enable default off/experimental](./docs/enable-default-off.md) detectors. The status of each detector can also be found [here](./docs/detectors/README.md) # Telemetry By default, telemetry will output to your output file path and will be a JSON blob. No data is submitted to Microsoft. From 9577546caec13b2864d4b9abb538d4f69c38edd5 Mon Sep 17 00:00:00 2001 From: Jamie Magee Date: Fri, 16 Jun 2023 13:19:21 -0700 Subject: [PATCH 4/4] PR comment changes --- docs/detectors/README.md | 114 +++++++++++++++++++-------------------- docs/detectors/npm.md | 19 +++++-- 2 files changed, 69 insertions(+), 64 deletions(-) diff --git a/docs/detectors/README.md b/docs/detectors/README.md index 3f5c5c742..2798f8ea7 100644 --- a/docs/detectors/README.md +++ b/docs/detectors/README.md @@ -2,110 +2,106 @@ - CocoaPods -| Detector| Status | -|-------|---------| -|PodComponentDetector | Stable | +| Detector | Status | +| -------------------- | ------ | +| PodComponentDetector | Stable | - DockerFile -| Detector| Status | -|-------|---------| -|DockerFileDetector | DefaultOff | +| Detector | Status | +| ------------------ | ---------- | +| DockerFileDetector | DefaultOff | - [Go](go.md) -| Detector| Status | -|-------|---------| -|GoComponentDetector | Stable | +| Detector | Status | +| ------------------- | ------ | +| GoComponentDetector | Stable | - [Gradle](gradle.md) -| Detector| Status | -|-------|---------| -|GradleComponentDetector | Stable | +| Detector | Status | +| ----------------------- | ------ | +| GradleComponentDetector | Stable | - Ivy -| Detector| Status | -|-------|---------| -|IvyDetector | Experimental | +| Detector | Status | +| ----------- | ------------ | +| IvyDetector | Experimental | - [Linux](linux.md) -| Detector| Status | -|-------|---------| -|LinuxContainerDetector | Stable | +| Detector | Status | +| ---------------------- | ------ | +| LinuxContainerDetector | Stable | - [Maven](maven.md) -| Detector| Status | -|-------|---------| -|MavenCliComponentDetector | Stable | +| Detector | Status | +| ------------------------- | ------ | +| MavenCliComponentDetector | Stable | - [NPM](npm.md) -| Detector| Status | -|-------|---------| -|NpmComponentDetector | Stable | -|NpmLockFileDetector | Stable | -|NpmLockFile3Detector | Experimental | +| Detector | Status | +| -------------------- | ------------ | +| NpmComponentDetector | Stable | +| NpmLockFileDetector | Stable | +| NpmLockFile3Detector | Experimental | - NuGet -| Detector| Status | -|-------|---------| -|NugetComponentDetector | Stable | -|NugetPackagesConfigDetector | Stable | -|NuGetProjectModelProjectCentricComponentDetector | Stable | +| Detector | Status | +| ------------------------------------------------ | ------ | +| NugetComponentDetector | Stable | +| NugetPackagesConfigDetector | Stable | +| NuGetProjectModelProjectCentricComponentDetector | Stable | - [Pip](pip.md) -| Detector| Status | -|-------|---------| -|PipComponentDetector | Stable | - +| Detector | Status | +| -------------------- | ------ | +| PipComponentDetector | Stable | - Pnpm -| Detector| Status | -|-------|---------| -|PnpmComponentDetector | Stable | - +| Detector | Status | +| --------------------- | ------ | +| PnpmComponentDetector | Stable | - [Poetry](poetry.md) -| Detector| Status | -|-------|---------| -|PoetryComponentDetector | Experimental | +| Detector | Status | +| ----------------------- | ------------ | +| PoetryComponentDetector | Experimental | - Ruby -| Detector| Status | -|-------|---------| -|RubyComponentDetector | Stable | +| Detector | Status | +| --------------------- | ------ | +| RubyComponentDetector | Stable | - Rust -| Detector| Status | -|-------|---------| -|RustCrateDetector | Stable | +| Detector | Status | +| ----------------- | ------ | +| RustCrateDetector | Stable | - Spdx -| Detector| Status | -|-------|---------| -|Spdx22ComponentDetector | DefaultOff | - +| Detector | Status | +| ----------------------- | ---------- | +| Spdx22ComponentDetector | DefaultOff | - Vcpkg -| Detector| Status | -|-------|---------| -|VcpkgComponentDetector | Experimental | - +| Detector | Status | +| ---------------------- | ------------ | +| VcpkgComponentDetector | Experimental | - Yarn -| Detector| Status | -|-------|---------| -|YarnLockDetector | Stable | \ No newline at end of file +| Detector | Status | +| ---------------- | ------ | +| YarnLockDetector | Stable | diff --git a/docs/detectors/npm.md b/docs/detectors/npm.md index e952e7909..171be8be1 100644 --- a/docs/detectors/npm.md +++ b/docs/detectors/npm.md @@ -2,14 +2,23 @@ ## Requirements - There are multiple detectors that make up npm detection and each detector searches for the following files: - - [The Npm Component detector looks for `package.json`](https://github.com/microsoft/component-detection/blob/251276d7951c7eaa880ed58b1a974b25dba92cd2/src/Microsoft.ComponentDetection.Detectors/npm/NpmComponentDetector.cs#L36) - - [The NpmLockFile detector looks for `package-lock.json`, `npm-shrinkwrap.json`,`lerna.json`](https://github.com/microsoft/component-detection/blob/251276d7951c7eaa880ed58b1a974b25dba92cd2/src/Microsoft.ComponentDetection.Detectors/npm/NpmLockfileDetectorBase.cs#L52) +There are multiple detectors that make up npm detection and each detector searches for the following files: + +- [The `NpmComponentDetector` detector searches for `package.json`][1] +- [The `NpmComponentDetectorWithRoots` and `NpmLockfile3Detector` detectors search for `package-lock.json`, `npm-shrinkwrap.json`, and `lerna.json`][2] ## Detection strategy - Npm detection searches for dependencies in `packages.json`, `package-lock.json`, `npm-shrinkwrap.json`(which are autogenerated by running npm init and other commands) as well as `lerna.json` in the scan directory. The lockfile detector is able to scan for transitive dependencies within the project. There is also an extension of the lockfile detector the NpmLockFilev3 detector that is able to scan [version 3 of lockfiles](https://github.com/microsoft/component-detection/blob/251276d7951c7eaa880ed58b1a974b25dba92cd2/src/Microsoft.ComponentDetection.Detectors/npm/NpmLockfile3Detector.cs#L36) +npm detectors search for dependencies in `packages.json`, `package-lock.json`, `npm-shrinkwrap.json` and `lerna.json` in the scan directory. +The lockfile detectors (`NpmComponentDetectorWithRoots` and `NpmLockfile3Detector`) are able to scan for transitive dependencies within the project. +There is also an extension of the lockfile detector the NpmLockFilev3 detector that is able to scan [version 3 of lockfiles][3] ## Known limitations -Npm has the option to download optional dependencies which can cause an overreporting issue with the detector. However this is not much of an issue currently since most projects only use dependencies and devdependencies. +Npm supports [`optionalDependencies`][4] which can cause an overreporting issue with the detector +However, this is not much of an issue as the majority of projects only use `dependencies` and `devDependencies`. + +[1]: https://github.com/microsoft/component-detection/blob/251276d7951c7eaa880ed58b1a974b25dba92cd2/src/Microsoft.ComponentDetection.Detectors/npm/NpmComponentDetector.cs#L36 +[2]: https://github.com/microsoft/component-detection/blob/251276d7951c7eaa880ed58b1a974b25dba92cd2/src/Microsoft.ComponentDetection.Detectors/npm/NpmLockfileDetectorBase.cs#L52 +[3]: https://github.com/microsoft/component-detection/blob/251276d7951c7eaa880ed58b1a974b25dba92cd2/src/Microsoft.ComponentDetection.Detectors/npm/NpmLockfile3Detector.cs#L36 +[4]: https://docs.npmjs.com/cli/v9/configuring-npm/package-json#optionaldependencies