Allow running code references in a specific subdirectory (#471)

This PR adds a new configuration option for specifying a location of the
`.launchdarkly/coderefs.yaml` config file if it's not located in the
root. This allows a monorepo to specify multiple config files, and will
require individual invocation:

```
ld-find-code-refs \
  --accessToken=<TOKEN> \
  --repoName=<REPO_NAME> \
  --dir="<LOCAL_DIR>" \
  --subdirectory="path/to/subdirectory" \
  --projKey="<PROJ_KEY>"
```

Author: stasquatch

build/metadata/bitbucket/README.md

@@ -17,6 +17,7 @@ Add the following snippet to the script section of your `bitbucket-pipelines.yml
     # LD_IGNORE_SERVICE_ERRORS "<boolean>" # Optional.
     # LD_LOOKBACK "<integer>" # Optional.
     # LD_ALLOW_TAGS "<boolean>" #Optional.
+    # LD_SUBDIRECTORY "<string>" # Optional.
 ```
 
 ## Variables

build/metadata/github-actions/README.md

@@ -83,19 +83,20 @@ Once your workflow has been created, the best way to confirm that the workflow i
 
 If the action fails, there may be a problem with your configuration. To investigate, dig into the action's logs to view any error messages.
 
-<!-- action-docs-inputs -->
+<!-- action-docs-inputs source="action.yml" -->
 ## Inputs
 
-| parameter | description | required | default |
+| name | description | required | default |
 | --- | --- | --- | --- |
-| accessToken | A token with write access to the LaunchDarkly project. | `true` |  |
-| allowTags | Enable storing references for tags. Lists the tag as a branch. | `false` | false |
-| baseUri | The base URL of the LaunchDarkly server for this configuration. | `false` | https://app.launchdarkly.com |
-| contextLines | The number of context lines above and below a code reference for the job to send to LaunchDarkly. By default, the flag finder will not send any context lines to LaunchDarkly. If < 0, it will send no source code to LaunchDarkly. If 0, it will send only the lines containing flag references. If > 0, it will send that number of context lines above and below the flag reference. You may provide a maximum of 5 context lines. | `false` | 2 |
-| debug | Enable verbose debug logging. | `false` | false |
-| ignoreServiceErrors | If enabled, the scanner will terminate with exit code 0 when the LaunchDarkly API is unreachable or returns an unexpected response. | `false` | false |
-| lookback | Set the number of commits to search in history for whether you removed a feature flag from code. You may set to 0 to disable this feature. Setting this option to a high value will increase search time. | `false` | 10 |
-| projKey | Key of the LaunchDarkly project associated with this repository. Found under Account Settings -> Projects in the LaunchDarkly dashboard. Cannot be combined with `projects` block in configuration file. | `false` |  |
-| repoName | The repository name. Defaults to the current GitHub repository. | `false` |  |
-| prune | There is a known issue where the GitHub Action will not prune deleted branch data in private repos. Only enable this if you are running the action in a public repo. | `false` | false |
-<!-- action-docs-inputs -->
+| `accessToken` | <p>A token with write access to the LaunchDarkly project.</p> | `true` | `""` |
+| `allowTags` | <p>Enable storing references for tags. Lists the tag as a branch.</p> | `false` | `false` |
+| `baseUri` | <p>The base URL of the LaunchDarkly server for this configuration.</p> | `false` | `https://app.launchdarkly.com` |
+| `contextLines` | <p>The number of context lines above and below a code reference for the job to send to LaunchDarkly. By default, the flag finder will not send any context lines to LaunchDarkly. If < 0, it will send no source code to LaunchDarkly. If 0, it will send only the lines containing flag references. If > 0, it will send that number of context lines above and below the flag reference. You may provide a maximum of 5 context lines.</p> | `false` | `2` |
+| `debug` | <p>Enable verbose debug logging.</p> | `false` | `false` |
+| `ignoreServiceErrors` | <p>If enabled, the scanner will terminate with exit code 0 when the LaunchDarkly API is unreachable or returns an unexpected response.</p> | `false` | `false` |
+| `lookback` | <p>Set the number of commits to search in history for whether you removed a feature flag from code. You may set to 0 to disable this feature. Setting this option to a high value will increase search time.</p> | `false` | `10` |
+| `projKey` | <p>Key of the LaunchDarkly project associated with this repository. Found under Account Settings -&gt; Projects in the LaunchDarkly dashboard. Cannot be combined with <code>projects</code> block in configuration file.</p> | `false` | `""` |
+| `repoName` | <p>The repository name. Defaults to the current GitHub repository.</p> | `false` | `""` |
+| `prune` | <p>There is a known issue where the GitHub Action will not prune deleted branch data in private repos. Only enable this if you are running the action in a public repo.</p> | `false` | `false` |
+| `subdirectory` | <p>The subdirectory to run the action in.</p> | `false` | `""` |
+<!-- action-docs-inputs source="action.yml" -->

build/metadata/github-actions/action.yml

@@ -42,6 +42,9 @@ inputs:
     default: "false"
     description: "There is a known issue where the GitHub Action will not prune deleted branch data in private repos. Only enable this if you are running the action in a public repo."
     required: false
+  subdirectory:
+    description: "The subdirectory to run the action in."
+    required: false
 runs:
   using: 'docker'
   image: 'Dockerfile'
@@ -56,3 +59,4 @@ runs:
     LD_IGNORE_SERVICE_ERRORS: ${{ inputs.ignoreServiceErrors }}
     LD_LOOKBACK: ${{ inputs.lookback }}
     LD_PRUNE: ${{ inputs.prune }}
+    LD_SUBDIRECTORY: ${{ inputs.subdirectory }}

docs/CONFIGURATION.md

@@ -29,21 +29,24 @@ ld-find-code-refs [flags]
 
 Flags:
 ```
-  -t, --accessToken string         LaunchDarkly personal access token with write-level access.
+    -t, --accessToken string         LaunchDarkly personal access token with write-level access.
 
       --allowTags                  Enables storing references for tags. The tag will be listed as a branch.
 
   -U, --baseUri string             LaunchDarkly base URI. (default "https://app.launchdarkly.com")
 
   -b, --branch string              The currently checked out branch. If not provided, branch name will be auto-detected. Provide this option when using CI systems that leave the repository in a detached HEAD state.
+
       --commitUrlTemplate string   If provided, LaunchDarkly will attempt to generate links to your VCS service provider per commit. Example: https://github.com/launchdarkly/ld-find-code-refs/commit/${sha}. Allowed template variables: 'branchName', 'sha'. If "commitUrlTemplate" is not provided, but "repoUrl" is provided and "repoType" is not custom, LaunchDarkly will attempt to automatically generate source code links for the given "repoType".
+      
   -C, --contextLines int           The number of context lines to send to LaunchDarkly. If < 0, no source code will be sent to LaunchDarkly. If 0, only the lines containing flag references will be sent. If > 0, will send that number of context lines above and below the flag reference. A maximum of 5 context lines may be provided. (default 2)
 
       --debug                      Enables verbose debug logging
 
   -B, --defaultBranch string       The default branch. The LaunchDarkly UI will default to this branch. If not provided, will fallback to 'main'. (default "main")
 
   -d, --dir string                 Path to existing checkout of the repository.
+
       --dryRun                     If enabled, the scanner will run without sending code references to LaunchDarkly. Combine with the outDir option to output code references to a CSV.
 
   -h, --help                       help for ld-find-code-refs
@@ -63,15 +66,18 @@ Flags:
   -r, --repoName string            Repository name. Will be displayed in LaunchDarkly. Case insensitive. Repository names must only contain letters, numbers, '.', '_' or '-'."
 
   -T, --repoType string            The repo service provider. Used to correctly categorize repositories in the LaunchDarkly UI. Acceptable values: bitbucket|custom|github|gitlab. (default "custom")
-
+  
   -u, --repoUrl string             The URL for the repository. If provided and "repoType" is not custom, LaunchDarkly will attempt to automatically generate source code links for the given "repoType".
 
   -R, --revision string            Use this option to scan non-git codebases. The current revision of the repository to be scanned. If set, the version string for the scanned repository will not be inferred, and branch garbage collection will be disabled. The "branch" option is required when "revision" is set.
 
+  --subdirectory string          If the .launchdarkly/coderefs.yaml file is not in the root of the repository, provide the path to the configuration file relative to the root.
+  Code references will only run on this provided subdirectory.
+
   -s, --updateSequenceId int       An integer representing the order number of code reference updates. Used to version updates across concurrent executions of the flag finder. If not provided, data will always be updated. If provided, data will only be updated if the existing "updateSequenceId" is less than the new "updateSequenceId". Examples: the time a "git push" was initiated, CI build number, the current unix timestamp. (default -1)
 
       --userAgent string           (Internal) Platform where code references is run.
-
+      
   -v, --version                    version for ld-find-code-refs
 ```
 

options/flags.go

@@ -142,6 +142,14 @@ LaunchDarkly UI. Acceptable values: bitbucket|custom|github|gitlab.`,
 		defaultValue: "",
 		usage:        `Use this option to scan non-git codebases. The current revision of the repository to be scanned. If set, the version string for the scanned repository will not be inferred, and branch garbage collection will be disabled. The "branch" option is required when "revision" is set.`,
 	},
+	{
+		name:         "subdirectory",
+		defaultValue: "",
+		usage: `If the .launchdarkly/coderefs.yaml file is not in the root of
+the repository, provide the path to the subdirectory containing the configuration,
+relative to the root. Code references will only run on this provided subdirectory.
+This allows a monorepo to have multiple configuration files, one per subdirectory.`,
+	},
 	{
 		name:         "updateSequenceId",
 		short:        "s",

options/options.go

@@ -57,6 +57,7 @@ type Options struct {
 	RepoType            string `mapstructure:"repoType"`
 	RepoUrl             string `mapstructure:"repoUrl"`
 	Revision            string `mapstructure:"revision"`
+	Subdirectory        string `mapstructure:"subdirectory"`
 	UserAgent           string `mapstructure:"userAgent"`
 	ContextLines        int    `mapstructure:"contextLines"`
 	Lookback            int    `mapstructure:"lookback"`
@@ -109,9 +110,11 @@ func InitYAML() error {
 	if err != nil {
 		return err
 	}
+	subdirectoryPath := viper.GetString("subdirectory")
 	viper.SetConfigName("coderefs")
 	viper.SetConfigType("yaml")
-	viper.AddConfigPath(filepath.Join(absPath, ".launchdarkly"))
+	configPath := filepath.Join(absPath, subdirectoryPath, ".launchdarkly")
+	viper.AddConfigPath(configPath)
 	err = viper.ReadInConfig()
 	if err != nil && !errors.As(err, &viper.ConfigFileNotFoundError{}) {
 		return err

search/scan.go

@@ -1,6 +1,8 @@
 package search
 
 import (
+	"path/filepath"
+
 	"github.com/launchdarkly/ld-find-code-refs/v2/flags"
 	"github.com/launchdarkly/ld-find-code-refs/v2/internal/ld"
 	"github.com/launchdarkly/ld-find-code-refs/v2/internal/log"
@@ -12,7 +14,12 @@ func Scan(opts options.Options, repoParams ld.RepoParams, dir string) (Matcher,
 	flagKeys := flags.GetFlagKeys(opts, repoParams)
 	matcher := NewMultiProjectMatcher(opts, dir, flagKeys)
 
-	refs, err := SearchForRefs(dir, matcher)
+	searchDir := dir
+	if opts.Subdirectory != "" {
+		searchDir = filepath.Join(dir, opts.Subdirectory)
+	}
+
+	refs, err := SearchForRefs(searchDir, matcher)
 	if err != nil {
 		log.Error.Fatalf("error searching for flag key references: %s", err)
 	}