docs: Feature/secureli 488 update documentation with new features (#563)

[secureli-488](#488)

Updating documentation for various features

**Note** this is branched off
`feature/secureli-397-document-config-file-usage`, as that hasn't yet
been merged and adds table of contents to the markdown files which
needed to be updated as part of this.

## Changes

- Updated docstrings to provide hints about function parameters which
hadn't been documented when they were added
- Added info to `README.md` on some features
- Moved language support information from `CONTRIBUTING.md` to
`README.md`

## Clean Code Checklist
<!-- This is here to support you. Some/most checkboxes may not apply to
your change -->
- [ ] Meets acceptance criteria for issue
- [ ] New logic is covered with automated tests
- [ ] Appropriate exception handling added
- [ ] Thoughtful logging included
- [x] Documentation is updated
- [ ] Follow-up work is documented in TODOs
- [ ] TODOs have a ticket associated with them
- [ ] No commented-out code included


<!--
Github-flavored markdown reference:
https://docs.github.com/en/get-started/writing-on-github
-->

CONTRIBUTING.md

@@ -10,7 +10,6 @@ https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one -
 - [Contributing to seCureLI](#contributing-to-secureli)
   - [Pull Requests](#pull-requests)
 - [Environment Requirements](#environment-requirements)
-  - [Supported Languages](#supported-languages)
   - [Python 3.9.9](#python-399)
   - [Setup macOS](#setup-macos)
   - [Setup Windows™](#setup-windows)
@@ -58,20 +57,6 @@ Refer to the [angular documentation](https://github.com/angular/angular/blob/mai
 
 # Environment Requirements
 
-## Supported Languages
-
-seCureLI has Slalom-maintained templates for security management of the following languages.
-
-- Java
-- Python
-- Terraform
-- JavaScript
-- TypeScript
-- C#
-- Swift
-- Golang
-- Kotlin
-
 ## Python 3.9.9
 
 This repo was started against Python 3.9.9, which released 11/15/2021. Security support will last until 10/05/2025. Newer versions should be fine, older versions will likely not work.

README.md

@@ -27,8 +27,10 @@ https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one -
   - [Help](#help)
   - [Init](#init)
   - [Scan](#scan)
+    - [Scanned Files](#scanned-files)
     - [PII Scan](#pii-scan)
   - [Custom Regex Scan](#custom-regex-scan)
+  - [Supported Languages](#supported-languages)
 - [Upgrade](#upgrade)
   - [Upgrading seCureLI via Homebrew](#upgrading-secureli-via-homebrew)
   - [Upgrading via pip](#upgrading-via-pip)
@@ -41,6 +43,7 @@ https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one -
     - [pii\_scanner](#pii_scanner)
     - [telemetry](#telemetry)
   - [pre-commit](#pre-commit)
+    - [Custom pre-commit configuration](#custom-pre-commit-configuration)
     - [Passing arguments to pre-commit hooks](#passing-arguments-to-pre-commit-hooks)
   - [`.secureli/repo-config.yaml`](#securelirepo-configyaml)
   - [Using Observability Platform to Show Secret Detection Statistics](#using-observability-platform-to-show-secret-detection-statistics)
@@ -123,6 +126,10 @@ To manually trigger a scan, run:
 
 This will run through all hooks and custom scans, unless a `--specific-test` option is used. The default is to scan staged files only. To scan all files instead, use the `--mode all-files` option.
 
+#### Scanned Files
+
+By default, seCureLI will only scan files that are staged for commit. If you want to scan a different set of files, you can use the `--file` parameter. You can specify multiple files by passing the parameter multiple times, e.g. `--file file1 --file file2`.
+
 #### PII Scan
 
 seCureLI utilizes its own PII scan, rather than using an existing pre-commit hook. To exclude a line from being flagged by the PII scanner, you can use a `disable-pii-scan` marker in a comment to disable the scan for that line.
@@ -138,6 +145,20 @@ seCureLI utilizes its own custom regex scan to flag any text that matches a user
 secureli update --new-pattern <your-custom-regex>
 ```
 
+### Supported Languages
+
+seCureLI has Slalom-maintained templates for security management of the following languages.
+
+- Java
+- Python
+- Terraform
+- JavaScript
+- TypeScript
+- C#
+- Swift
+- Golang
+- Kotlin
+
 ## Upgrade
 
 ### Upgrading seCureLI via Homebrew
@@ -210,6 +231,10 @@ seCureLI is configurable via a `.secureli.yaml` file present in the root of your
 
 [pre-commit](https://pre-commit.com/) is used for configuring pre-commit hooks. The configuration file is `.secureli/.pre-commit-config.yaml`, relative to the root of your repo. For details on modifying this file, see the pre-commit documentation on [configuring hooks](https://pre-commit.com/#pre-commit-configyaml---hooks).
 
+#### Custom pre-commit configuration
+
+If there is a `.pre-commit-config` file in your root when you initialize seCureLI, it will be merged with the default configuration written to `.secureli/.pre-commit-config.yaml`.
+
 #### Passing arguments to pre-commit hooks
 
 Special care needs to be taken when passing arguments to pre-commit hooks in `.pre-commit-config.yaml`. In particular, if you're passing parameters which themselves take arguments, you must ensure that both the parameter and its arguments are separate items in the array.

secureli/actions/action.py

@@ -375,6 +375,7 @@ def _detect_languages(self, folder_path: Path, files: list[Path]) -> list[str]:
         """
         Detects programming languages present in the repository
         :param folder_path: The folder path to initialize the repo for
+        :param files: A List of files to scope the install to. This allows language detection to run on only a selected list of files when scanning the repo.
         :return: A list of all languages found in the repository
         """
 

secureli/actions/scan.py

@@ -93,6 +93,7 @@ def scan_repo(
         :param scan_mode: How we should scan the files in the repo (i.e. staged only or all)
         :param always_yes: Assume "Yes" to all prompts
         :param specific_test: If set, limits scanning to the single pre-commit hook.
+        :param files: If set, scans only the files provided.
         Otherwise, scans with all hooks.
         """
 

secureli/modules/language_analyzer/language_analyzer.py

@@ -24,6 +24,7 @@ def analyze(self, folder_path: Path, files: list[Path]) -> AnalyzeResult:
         """
         Analyzes the folder structure and lists languages found
         :param folder_path: The path to the repository to analyze
+        :param files: A list of files to analyze. If not provided, all files in the repo will be analyzed
         :return: Produces an ordered dictionary of languages detected and what percentage
         of the repo is each language. For example, if 60% of the repo is Python files and
         40% of the repo is JavaScript, the result will be a dictionary containing keys