Update to detector docs (#608)

Added documentation for Npm and status for each detector --------- Co-authored-by: Jamie Magee <[email protected]>
microsoft · Jun 16, 2023 · d95e235 · d95e235
1 parent d92e45c
commit d95e235
Show file tree

Hide file tree

Showing 3 changed files with 120 additions and 2 deletions.
diff --git 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.

diff --git a/docs/detectors/README.md b/docs/detectors/README.md
@@ -1,13 +1,107 @@
 # 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)
-- NPM
+
+| 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 |
diff --git a/docs/detectors/npm.md b/docs/detectors/npm.md
@@ -0,0 +1,24 @@
+# Npm Detection
+
+## Requirements
+
+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 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 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