Refactor Compile.ps1 Script for Modularity and Enhanced Functionality

[fam007e]

Type of Change

• Refactoring
• New feature
• Documentation update

Description

This pull request refactors the Compile.ps1 script with the following key improvements:

• Moved Update-Progress Function:

  • The Update-Progress function has been moved to an external script for better modularity and reusability.

• Added Encode-JsonSpecialChars Function:

  • A new function, Encode-JsonSpecialChars, has been introduced to handle JSON special character encoding more effectively. This improves the robustness of JSON handling and prevents potential formatting issues.

• Implemented Error Handling:

  • Error handling has been enhanced with try/catch blocks during preprocessing and compilation steps, ensuring that issues are caught and handled gracefully.

• Introduced Logging Functionality:

  • Logging has been added to track progress and capture errors during the script execution. This provides better traceability and helps in debugging.

• Improved Path Handling:

  • Paths are now handled using $PSScriptRoot and Join-Path for better portability across different environments. This change improves the script's reliability when run in various directory structures.

Testing

• The script was tested in both Windows PowerShell and PowerShell Core environments.
• The -Debug, -Run, and -SkipPreprocessing switches were tested to confirm that they function as expected.
• The syntax validation feature was tested to ensure that it catches common errors in the generated script.
• Logging was verified to ensure that all steps and errors are properly captured.

Impact

• The refactoring enhances the maintainability and readability of the Compile.ps1 script.
• The improved modularity allows for easier updates and potential reusability of components in other scripts.
• The introduction of error handling and logging makes the script more robust and easier to debug.

Issue related to PR

• Resolves #

Additional Information

• This refactoring is part of a larger effort to improve the overall code quality of the project. Future updates may include further modularization or additional features to enhance functionality.

Checklist

• My code adheres to the coding and style guidelines of the project.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation.
• My changes generate no errors/warnings/merge conflicts.

[Real-MullaC]

This only changes 1 file and does not add any files.

[og-mrk]

@fam007e Because of the new changes introduced in this PR, new .log files will be created when running Compile.ps1 script.. which might accidently be added in the future, and because these logs are for error checking/diagnosis.. It's a good to ignore (not track) these files by git (the version management system used by this project, and every project on GitHub).

To do so (ignore .log files) you can add the following line in .gitignore file:

*.log

[og-mrk]

After further testing, turns out that these changes have several problems, major one is the json parsing part (it appears as if doesn't do its job correctly), resulting in Syntax Errors.

Plus there's currently a bug in Invoke-Preprocessing script, where it doesn't test the possibility of an absolute file paths in Exclude Files List.. resulting in false positives in the validation step, I'll resolve this bug in PR #2579.

[og-mrk]

@fam007e I've fixed in PR 1 (on your fork) the issues described in this review comment. Please consider reviewing my PR over on your fork, and test my changes after merging it. Thanks in advance 😄

[og-mrk]

@fam007e I would like to say, first and foremost.. thanks for your contribution, it's awesome to see others contribute to WinUtil, no matter how simple/complex their changes might be...

With that being said, and after some changes done to PR #2465 by @MyDrift-user (a somewhat medium sized Refactoring PR).. so the changes in this PR are not needed. I hope this doesn't discourages you from contributing to this project or other open source projects.. as WinUtil recently is in active development from several contributors, so conflict in interests may arise.

I recommend waiting to see @ChrisTitusTech opinion on this, but from a technical stand point these changes of yours will cause some problems, not to mention you'll need to update Compile.ps1 script, that's.. if PR #2465 is merged in the first place.

EDIT: Please note changes related to separation of Update-Progress won't be affected, and I do think it's a good idea to re-use code, as Update-Progress is Copy-Pasted in tools/devdocs-generator.ps1 script as well 😅