Document the target field of .fossa.yml target filters

docs/references/files/fossa-yml.md

@@ -290,6 +290,20 @@ Targets are listed in the following formats for both `only` and `exclude` lists.
     - type: pipenv (all pipenv type targets at any path)
 ```
 
+Some project types divide a single project into named build targets — for
+example each package of a yarn or npm workspace. Add a `target` field alongside
+`path` to select one of them:
+
+```yaml
+    - type: yarn
+      path: ./
+      target: app
+```
+
+This is the `.fossa.yml` equivalent of `--only-target 'yarn@./:app'`. Run
+`fossa list-targets` to see which targets a project has; a project with no named
+targets is selected by `type` and `path` alone.
+
 #### `targets.only:`
 The list of `only` targets that should be scanned. When used alongside `paths.only`, the intersection of the two lists is taken to find targets for scanning
 
@@ -369,7 +383,7 @@ For detailed walkthrough, and example please refer to [analysis target configura
 
 #### Project target configuration example
 
-Run the command `fossa list-targets` to determine the analysis targets present in your project. The output will look similar to the following with the targets in format `type@path` (You may see that duplicated lines for "Found target" and "Found project"):
+Run the command `fossa list-targets` to determine the analysis targets present in your project. The output will look similar to the following with the targets in format `type@path`, or `type@path:target` for a project divided into named build targets (You may see that duplicated lines for "Found target" and "Found project"):
 
 ```
 Found target: bundler@prod/docker

docs/references/files/fossa-yml.v3.schema.json

@@ -131,6 +131,12 @@
         },
         "targetFilter": {
             "type": "object",
+            "allOf": [
+                {
+                    "if": { "required": ["target"] },
+                    "then": { "required": ["path"] }
+                }
+            ],
             "properties": {
                 "type": {
                     "type": "string",
@@ -281,6 +287,10 @@
                 "path": {
                     "type": "string",
                     "description": "Associated path with target type (if any)"
+                },
+                "target": {
+                    "type": "string",
+                    "description": "A named build target within the project at `path`, for project types that have them (for example each package of a yarn or npm workspace). Requires `path`. Run `fossa list-targets` to see a project's target names."
                 }
             }
         },

docs/references/subcommands/list-targets.md

@@ -16,6 +16,17 @@ $ fossa list-targets
 
 This output tells us that when `fossa analyze` is run, we will be analyzing `cabal`, `cocoapods`, `pipenv`, and `yarn` projects. This can be useful to determine if there are targets you expect or don't expect to see.
 
+A project that is divided into named build targets, such as a yarn, npm, or pnpm workspace, is listed once per target in the form `type@path:target`:
+
+```bash
+$ fossa list-targets
+[ INFO] Found target: yarn@./:my-monorepo
+[ INFO] Found target: yarn@./:app
+[ INFO] Found target: yarn@./:lib-core
+```
+
+Each of those can be selected on its own with `fossa analyze --only-target 'yarn@./:app'`, or with a `target:` field on a `targets.only` entry in `.fossa.yml` (`targets.exclude` leaves it out instead); see [analysis target configuration](../files/fossa-yml.md#analysis-target-configuration).
+
 #### Command output formats
 
 The list-targets command supports the following formats (via `fossa list-targets --format=<OPTION>`):