Update README.md and add SettingsFileDocumentation.md for Invoke-ScriptAnalyzer action

Author: MariusStorhaug

README.md

@@ -1,17 +1,109 @@
-# Template-Action
+```markdown
+# Invoke-ScriptAnalyzer (by PSModule)
 
-A template repository for GitHub Actions
+This repository contains a GitHub Action that runs PSScriptAnalyzer on your code.
+The action analyzes PowerShell scripts using a hashtable-based settings file to
+customize rule selection, severity filtering, and custom rule inclusion.
 
-## Usage
+> **Note:** This repository includes automated tests that run via Pester to ensure
+> your settings file is working as expected.
 
-### Inputs
+## Action Details
 
-### Secrets
+- **Name:** Invoke-ScriptAnalyzer (by PSModule)
+- **Description:** Runs PSScriptAnalyzer on the code.
+- **Author:** PSModule
+- **Branding:**
+  Icon: `check-square`
+  Color: `gray-dark`
 
-### Outputs
+## Inputs
 
-### Example
+| Input               | Description                                                       | Required | Default                                                                     |
+|---------------------|-------------------------------------------------------------------|----------|-----------------------------------------------------------------------------|
+| **Path**            | The path to the code to test.                                     | Yes      | `${{ github.workspace }}`                                                   |
+| **Settings**        | The type of tests to run: `Module`, `SourceCode`, or `Custom`.    | No       | `Custom`                                                                    |
+| **SettingsFilePath**| If `Custom` is selected, the path to the settings file.           | No       | `${{ github.workspace }}/.github/linters/.powershell-psscriptanalyzer.psd1` |
+
+## Outputs
+
+| Output  | Description                           | Value                                      |
+|---------|---------------------------------------|--------------------------------------------|
+| passed  | Indicates if the tests passed.      | `${{ steps.test.outputs.Passed }}`         |
+
+## Files Overview
+
+- **action.yml**
+  Describes the action inputs, outputs, and run steps. The action uses a
+  composite run steps approach with two main steps:
+  1. **Get test paths:** Uses a script to resolve paths and settings.
+  2. **Invoke-Pester:** Runs Pester tests against PSScriptAnalyzer.
+
+- **scripts/main.ps1**
+  Determines the correct settings file path based on the test type. It
+  supports testing a module, source code, or using a custom settings file.
+
+- **scripts/tests/PSScriptAnalyzer/**
+  Contains Pester tests that run PSScriptAnalyzer using the provided settings
+  file. The tests check for issues reported by PSScriptAnalyzer based on rule
+  configuration.
+
+## How It Works
+
+1. **Path Resolution:**
+   The action reads inputs and determines the code path, test path, and the
+   settings file path. For custom settings, it uses the file at:
+   ```
+   .github/linters/.powershell-psscriptanalyzer.psd1
+   ```
+   Otherwise, it uses a default settings file from the test folder.
+
+2. **Pester Testing:**
+   The tests import the settings file and use `Invoke-ScriptAnalyzer` to scan
+   the code. Each rule is evaluated, and if a rule violation is found, the test
+   will fail for that rule. Rules that are marked to be skipped (via exclusions
+   in the settings file) are automatically skipped in the test.
+
+3. **Automation:**
+   Designed for CI/CD, this action integrates with GitHub Actions, Azure Pipelines,
+   and other systems. The settings file customizes analysis, letting you control
+   rule inclusion, severity filtering, and custom rule paths.
+
+## Example Workflow
+
+Below is an example workflow configuration using this action:
 
 ```yaml
-Example here
+name: Analyze PowerShell Code
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Invoke PSScriptAnalyzer
+        uses: PSModule/Invoke-ScriptAnalyzer@v1
+        with:
+          Path: ${{ github.workspace }}
+          Settings: Custom
+          SettingsFilePath: ${{ github.workspace }}/.github/linters/.powershell-psscriptanalyzer.psd1
+```
+
+## Appendix: Settings File Documentation
+
+For detailed documentation on the format of the settings file, see the
+[Settings File Documentation](./SettingsFileDocumentation.md) file.
+
+## References and Links
+
+- [PSScriptAnalyzer Documentation](https://learn.microsoft.com/powershell/module/psscriptanalyzer/)
+- [GitHub Super-Linter](https://github.com/github/super-linter)
+- [PSScriptAnalyzer GitHub Repository](https://github.com/PowerShell/PSScriptAnalyzer)
+- [Custom Rules in PSScriptAnalyzer](https://docs.microsoft.com/powershell/scripting/developer/hosting/psscriptanalyzer-extensibility)
+
+## License
+
+This project is licensed under the MIT License.
 ```

Rules.md SettingsFileDocumentation.mdRules.md renamed to SettingsFileDocumentation.md

@@ -1,5 +1,5 @@
-name: Test-PSModule (by PSModule)
-description: Test a PowerShell module before publishing the module to the PowerShell Gallery.
+name: Invoke-ScriptAnalyzer (by PSModule)
+description: Runs PSScriptAnalyzer on the code.
 author: PSModule
 branding:
   icon: check-square
@@ -15,7 +15,7 @@ inputs:
     required: false
     default: 'Custom'
   SettingsFilePath:
-    description: The path to the settings file.
+    description: If 'Custom' is selected, the path to the settings file.
     required: false
     default: ${{ github.workspace }}/.github/linters/.powershell-psscriptanalyzer.psd1