🩹 [Patch]: Add Linter settings + fix documentation structure (#535)

## Description

This pull request primarily fixes the documentation of PowerShell
functions by adding PowerShell-formatted code blocks to the `.EXAMPLE`
sections, due to upgrading from `platyPS` to
`Microsoft.PowerShell.PlatyPS`. Additionally, it introduces
configuration changes for linters and minor formatting corrections.

Documentation improvements:

* Added PowerShell-formatted code blocks to the `.EXAMPLE` sections of
many function files in `src/functions/*`. This was needed to retain the
code blocks in the examples, as `Microsoft.PowerShell.PlatyPS` lets the
user configure this.

Linter and configuration updates:

* Added a `Linter` section to `.github/PSModule.yml` to explicitly
disable several validation checks, such as `VALIDATE_BIOME_FORMAT` and
`VALIDATE_POWERSHELL`.
* Fixed a minor formatting issue in `.github/linters/.markdown-lint.yml`
by changing double quotes to single quotes for the `MD026.punctuation`
setting. This was also due to `Microsoft.PowerShell.PlatyPS` adding H3
for types which can be same for `.INPUTS` and `.OUTPUTS`.

Encoding and formatting corrections:

* Added or corrected UTF-8 BOM in some PowerShell files to ensure proper
encoding.

🩹 [Patch]: Bump Process-PSModule to v5 (#533)

This pull request updates and simplifies the repository's GitHub
workflow and configuration files, focusing on workflow consolidation,
dependency management, and configuration cleanup. The main changes
include merging the nightly and pull request workflows, updating
workflow versions, improving Dependabot labeling, and removing unused
configuration files.

**Workflow consolidation and updates:**

* Combined the nightly scheduled workflow and the pull request workflow
into a single `.github/workflows/Process-PSModule.yml` file, which now
runs on both a nightly schedule and on pull requests to `main`. The
workflow was also updated to use `workflow.yml@v5` and to inherit
secrets, simplifying maintenance.
[[1]](diffhunk://#diff-b4dbaea65a86cef96799e9783b18b31e96a456d476805312f52919d45a060603L3-R6)
[[2]](diffhunk://#diff-b4dbaea65a86cef96799e9783b18b31e96a456d476805312f52919d45a060603L29-R31)
[[3]](diffhunk://#diff-ae7e03d0a8740974e1848d0dc7322a8b3f3f4898b37bfd5b226dff69096bb8dfL1-L24)
* Removed the separate `.github/workflows/Nightly-Run.yml` and
`.github/workflows/Linter.yml` files, consolidating workflow logic and
eliminating redundant jobs.
[[1]](diffhunk://#diff-ae7e03d0a8740974e1848d0dc7322a8b3f3f4898b37bfd5b226dff69096bb8dfL1-L24)
[[2]](diffhunk://#diff-482e65806ed9e4a7320f14964764086b91fed4a28d12e4efde1776472e147e79L1-L33)

**Dependency management:**

* Updated `.github/dependabot.yml` to automatically add `dependencies`
and `github-actions` labels to PRs created for GitHub Actions updates,
improving visibility and triage of dependency updates.

**Configuration cleanup:**

* Removed the `.github/linters/.jscpd.json` file, indicating that JSCPD
duplicate code detection is no longer configured or required in this
repository.
* Added a new `.github/PSModule.yml` configuration file to set a code
coverage target for tests, supporting the Process-PSModule workflow.

🩹 [Patch]: Performance improvement by saving the GitHub App info in G…

…itHubAppContext (#531)

## Description

This pull request introduces several improvements for handling GitHub
object construction and context management, focusing on increased
robustness and compatibility with varied input shapes. The main changes
include more flexible property assignment using null coalescing,
refactoring constructors for consistency, and enhancing context
propagation for GitHub Apps and Installations.

### Main change

Remove API calls to get the Application for the authenticated app when
getting app installations. Instead, we store the application info for
the app in its app context, and transfer that to the app as we configure
the app installations. In short, less API calls => better performance.

### Improved object construction and property assignment

* All major classes (`GitHubApp`, `GitHubAppInstallation`,
`GitHubOwner`, `GitHubUser`, `GitHubOrganization`, `GitHubEnterprise`,
and `GitHubPlan`) now use null coalescing (`??`) for property
assignment, allowing them to accept alternate property names and
fallback values when constructing from different input shapes. This
increases compatibility with API responses and internal/stored objects.

* Refactored the `GitHubOrganization` constructor to use an
`InitializeFromObject` method, improving code reuse and making it easier
to support multiple initialization patterns.

### Improved handling of GitHub App and Installation context

* The `GitHubAppContext` class now has a dedicated `$App` property, and
its constructor initializes it when available, ensuring the
authenticated app context is propagated correctly.

* Functions that create `GitHubAppInstallation` objects now consistently
pass the authenticated app from context (`$Context.App`), rather than
fetching it separately, ensuring correct permission comparison and
status setting.

* The `GitHubAppInstallation` constructor and related logic now support
both direct object assignment and fallback property mapping for the
`App` and `Target` properties, increasing flexibility and correctness.

### Miscellaneous improvements

* The organization retrieval function now constructs organization URLs
directly from context, removing dependency on context objects and
improving reliability.

* Minor bug fix in `Remove-GitHubContext` for variable casing.

* When setting context, the authenticated app is now stored in the
context object for downstream use.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [x] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

🩹 [Patch]: Update `Connect-GitHubApp` to support installation ID para…

…meter (#525)

## Description

This pull request adds support for connecting to a GitHub App
installation using an explicit installation ID, improving flexibility
and usability in authentication scenarios. The main changes involve
updating the `Connect-GitHubApp` function to accept installation IDs
directly and adding corresponding tests to ensure the new functionality
works as expected.

**Enhancements to authentication logic:**

* Updated the `Connect-GitHubApp.ps1` function to accept an `-ID`
parameter, allowing users to connect directly to installations by their
ID. This replaces the previous pipeline-based `Installation` parameter
with a more flexible approach.
* Added logic to process the new `InstallationID` parameter set,
including verbose logging and warnings when an installation ID is not
found.

**Testing improvements:**

* Added a new test case in `Apps.Tests.ps1` to verify that
`Connect-GitHubApp` successfully connects using the `-ID` parameter for
a single installation, checking key properties of the returned context
object.
* Updated test setup to retrieve the installation object for use in the
new test scenario.

**General improvements:**

* Refactored code to ensure installations are only retrieved when
necessary, improving efficiency and clarity.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [x] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

🚀 [Breaking pre-release]: Refactor GitHubPermission and improve initi…

…alization and comparison logic (#524)

## Description

This pull request refactors how GitHub permissions are represented and
handled throughout the codebase, consolidating the
`GitHubPermissionDefinition` and `GitHubPermission` classes and updating
related logic for consistency and correctness. The changes also improve
the handling of permissions and events in context and installation
classes, as well as streamline status calculation for installations.

### Refactoring and Consolidation of Permissions

* Merged `GitHubPermissionDefinition` into a single `GitHubPermission`
class, adding constructors and properties to better represent both
definitions and assigned values. All static permission lists and related
logic now use `GitHubPermission` instead of the previous definition
class.
* Updated all permission list instantiations to use the new
`GitHubPermission` class, ensuring consistent construction and type
usage.

### Improvements to Installation and Context Classes

* Updated constructors in `GitHubAppInstallation.ps1` to use a simpler
parameter set, replaced `$Context.HostName` with direct `$HostName`
usage, and removed a redundant constructor. Also changed the status
update method name from `UpdateStatus` to `SetStatus` and adjusted its
usage.
* Improved event and permission handling in `GitHubAppContext.ps1` and
`GitHubAppInstallationContext.ps1` by ensuring events are always stored
as arrays and permissions are only set when present.
* Ensured `FilePaths` and `Events` properties are always arrays to
prevent type inconsistencies.

### Streamlining Installation Status Calculation

* Refactored the logic for comparing permissions in `SetStatus`,
replacing manual dictionary comparison with a simpler `Compare-Object`
approach for determining if permissions match between app and
installation.
* Added a check to ensure that installation permissions exist before
attempting status calculation, improving robustness.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [x] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

🚀 [Breaking pre-release]: Remove `AppID` from `GitHubApp` (#523)

## Description

This pull request removes the `AppID` property from the `GitHubApp`
class and eliminates its usage throughout the codebase. The changes help
simplify the class structure and ensure consistency in object
construction.

Class structure simplification:

* Removed the `AppID` property from the `GitHubApp` class definition in
`src/classes/public/App/GitHubApp.ps1`.
* Removed assignment of `AppID` in the `GitHubApp` constructor in
`src/classes/public/App/GitHubApp.ps1`.

Object construction consistency:

* Removed the `app_id` property when creating `GitHubApp` objects in
both constructors of the `GitHubAppInstallation` class in
`src/classes/public/App/GitHubAppInstallation.ps1`.
[[1]](diffhunk://#diff-c1442a9fa3e51d2f0bf378039e97400122a24423d72d534112ca6f7c06a5ffaeL54)
[[2]](diffhunk://#diff-c1442a9fa3e51d2f0bf378039e97400122a24423d72d534112ca6f7c06a5ffaeL94)

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [x] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

🪲 [Fix]: Fixing the `Secrets` test for `PublicKey` for `codespaces` (#…

…518)

## Description

This pull request updates the `Secrets.Tests.ps1` test suite to improve
how the `Get-GitHubPublicKey` command is tested for different
organization plans and makes a minor formatting change to a log message.

Test logic improvements for organization plan handling:

* Updated the `Get-GitHubPublicKey -Type codespaces` test to
conditionally expect a throw for organizations on the 'free' plan, and
to run the usual public key retrieval for other plans. This ensures the
test behaves correctly based on the organization's plan type.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [x] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

🚀[Feature]: Permission infrastructure + Track GitHub App Installation…

… status (#513)

This pull request introduces several improvements to how GitHub App
permissions are represented, compared, and displayed throughout the
codebase. The main focus is on replacing the use of generic objects for
permissions with a strongly-typed `GitHubPermission` class, adding
installation status comparison logic, and enhancing output formatting
for better user experience.

- Fixes #510

Key changes include:

**Permission Model Refactor:**

* Replaces all uses of `[pscustomobject]` for permissions in
`GitHubApp`, `GitHubAppInstallation`, `GitHubAppContext`, and
`GitHubAppInstallationContext` with `[GitHubPermission[]]`, ensuring
permissions are strongly typed and consistently handled.
* Colocate `GitHubPermissionDefinition` class with the
`GitHubPermission` in the `GitHubPermission.ps1` file.

**Installation Status and Comparison Logic:**

* Adds a `Status` property to `GitHubAppInstallation` and implements
logic to compare installation permissions with app permissions, setting
status as `'Ok'` or `'Outdated'` accordingly.
* Updates `Get-GitHubAppInstallationForAuthenticatedApp` to pass the
authenticated app object to each installation for accurate status
calculation.

**Formatting and Output Enhancements:**

* Updates the `GitHubAppInstallation` format XML to display the new
`Status` property in both table and list views, using symbols and colors
when supported for better clarity.
* Adds a new format file for `GitHubPermission`, improving how
permissions are displayed in the console, including hyperlinks for
permission names when supported.

**Configuration and Miscellaneous:**

* Makes the `Context` parameter mandatory and positional in
`Switch-GitHubContext` for improved usability.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: MariusStorhaug <17722253+MariusStorhaug@users.noreply.github.com>
Co-authored-by: Marius Storhaug <marstor@hotmail.com>

🚀[Feature]: Add a config for how to match argument completers (#512)

This pull request introduces a new configurable completion mode for
argument completers, allowing users to choose between 'StartsWith' and
'Contains' matching for tab completion throughout the module. It also
improves the config initialization logic to better synchronize stored
configuration objects with the current class definition, ensuring
obsolete properties are removed and new ones are added automatically.

- Fixes #509

**Configurable Completion Mode:**

* Added a new `CompletionMode` property to the `GitHubConfig` class,
allowing users to select between 'StartsWith' and 'Contains' matching
for argument completion. This property is now included in the config
display format.
* Updated all argument completer scripts to use the `CompletionMode`
from config, switching between prefix and substring matching as
specified. This affects completers for contexts, organizations,
environments, gitignore, licenses, permissions, and repository
permissions.
* Added a value completer for the `CompletionMode` property itself,
suggesting 'StartsWith' and 'Contains' when setting the config.

**Configuration Management Improvements:**

* Enhanced the `Initialize-GitHubConfig` function to automatically add
new properties and remove obsolete ones from stored configs, ensuring
the config object stays in sync with the class definition.

**Minor Usability Improvement:**

* Made the `Context` parameter in `Get-GitHubContext` positional for
easier use.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: MariusStorhaug <17722253+MariusStorhaug@users.noreply.github.com>
Co-authored-by: Marius Storhaug <marstor@hotmail.com>

🩹 [Patch]: Fix and align argument completers (#508)

This pull request introduces several improvements and refactors across
argument completer scripts, license and gitignore handling, and data
formatting. The main goals are to standardize completer parameter usage,
enhance context-awareness and filtering, improve data sorting and
output, and clarify the license data model.

- Fixes #486

**Key changes:**

### Argument Completer Improvements and Refactoring

* Updated all argument completers to use `$fakeBoundParameters` instead
of `$fakeBoundParameter`, ensuring consistency and enabling
context-aware completions across the module. Added filtering and context
parameters where appropriate.
[[1]](diffhunk://#diff-22b2affe76b37eaa2b3cdee057e05020af8aa4890e0966e676e4a936d828e4e4L2-R3)
[[2]](diffhunk://#diff-22b2affe76b37eaa2b3cdee057e05020af8aa4890e0966e676e4a936d828e4e4L15-R18)
[[3]](diffhunk://#diff-775e15ad0206292ebf4f5d7659e274c2384326d9b0e9821b96280186769ba4d8L2-R3)
[[4]](diffhunk://#diff-ba8339f3d5f55d7346080dc2bd24097cc8d0bc87fc027a237bfa53617224b25eL1-R26)
[[5]](diffhunk://#diff-7d92b4f19fe6156533814de81d6618281c98a1914b85a2373be2638b660f0a96L5-R37)
[[6]](diffhunk://#diff-dc5710dd4a873f6fe7a26f241fd8261acdb594962c405f48982396275d6a530fR1-R12)
[[7]](diffhunk://#diff-eb8a0b19f6f2c88ecc3a09e6544d51dc0c5d8c61ad4f8fe40d544fc182c0ac91R1-R12)
[[8]](diffhunk://#diff-792b150421507ebd45a85f5eedf88b6fc3ead29405ceff31779746e5cd5bf7c7R1-R39)
* Moved and refactored several completers (for `Get-GitHubLicense`,
`Get-GitHubGitignore`, and `Connect-GitHubApp`) into their own dedicated
`completers.ps1` files, and removed the old implementations.
[[1]](diffhunk://#diff-de6b8171283593a8a3424849e06ab22a6d6ead1c9a677db2f91ffa2225759363L87-L94)
[[2]](diffhunk://#diff-349ba6d13800f374dc911b94db55e01a2e50be26859901f1eccf6a94d85ee05cL70-L77)
[[3]](diffhunk://#diff-2fcb088cf090e075faa3b356b6d08d341de9167e4e69d5270f34f7faf46e6cd7L1-L27)

### License Model and Formatting Updates

* Changed the `GitHubLicense` class to clarify property names: `Key` is
now `Name`, and `Name` is now `DisplayName`, with corresponding updates
to the constructor and format file.
[[1]](diffhunk://#diff-98f2ef3a26cb403b39286027e24110885695960c6c8b26853bd2af0c62e9f15eL26-R32)
[[2]](diffhunk://#diff-98f2ef3a26cb403b39286027e24110885695960c6c8b26853bd2af0c62e9f15eL81-R82)
[[3]](diffhunk://#diff-f3cb0ef91f12f89dc4c0b19bb042e6e2c4a71bb4040b46a853e4c71916c43e98L11-L32)
[[4]](diffhunk://#diff-f3cb0ef91f12f89dc4c0b19bb042e6e2c4a71bb4040b46a853e4c71916c43e98L44-L85)
* Updated the license format table to display the new property names and
removed less relevant columns for a cleaner output.
[[1]](diffhunk://#diff-f3cb0ef91f12f89dc4c0b19bb042e6e2c4a71bb4040b46a853e4c71916c43e98L11-L32)
[[2]](diffhunk://#diff-f3cb0ef91f12f89dc4c0b19bb042e6e2c4a71bb4040b46a853e4c71916c43e98L44-L85)

### Context and Filtering Enhancements

* Improved context handling and filtering for completers, ensuring that
completions are accurate with respect to the current context and user
input.
[[1]](diffhunk://#diff-22b2affe76b37eaa2b3cdee057e05020af8aa4890e0966e676e4a936d828e4e4L15-R18)
[[2]](diffhunk://#diff-7d92b4f19fe6156533814de81d6618281c98a1914b85a2373be2638b660f0a96L5-R37)
[[3]](diffhunk://#diff-ba8339f3d5f55d7346080dc2bd24097cc8d0bc87fc027a237bfa53617224b25eL1-R26)
[[4]](diffhunk://#diff-dc5710dd4a873f6fe7a26f241fd8261acdb594962c405f48982396275d6a530fR1-R12)
[[5]](diffhunk://#diff-eb8a0b19f6f2c88ecc3a09e6544d51dc0c5d8c61ad4f8fe40d544fc182c0ac91R1-R12)
* Added support for `App` authentication to `Get-GitHubLicense`, and
ensured that if the context is an App, it falls back to anonymous.

### Data Sorting and Output Consistency

* Ensured that results from `Get-GitHubAppInstallation` are sorted by
`Type` and `Target` for more predictable output.
[[1]](diffhunk://#diff-9ca965372ef6314e8f8759ce87dedff3c8a0d216fe06fda41e0fb38b89722dfeL60-R60)
[[2]](diffhunk://#diff-9ca965372ef6314e8f8759ce87dedff3c8a0d216fe06fda41e0fb38b89722dfeR81)

### Miscellaneous

* Commented out an unused `Accept` header in the gitignore API call,
likely to prevent issues with response formatting.

These changes collectively improve the maintainability, usability, and
consistency of the module's command-line experience.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: MariusStorhaug <17722253+MariusStorhaug@users.noreply.github.com>
Co-authored-by: Marius Storhaug <marstor@hotmail.com>