rules.xml

<?xml version="1.0" encoding="UTF-8"?>
<rules>
  <the_most_important_rule>
    THE ABSOLUTE PRIORITY, TRUMPING EVERYTHING ELSE, IS TO LEVERAGE ZSH-SPECIFIC SYNTAX AND FEATURES TO THEIR FULLEST EXTENT. WE EXPLICITLY REJECT POSIX SHELL COMPATIBILITY IN FAVOR OF ZSH'S ADVANCED CAPABILITIES ON MACOS/DARWIN. EVERY SCRIPT MUST USE ZSH-SPECIFIC PARAMETER EXPANSION, ARRAY HANDLING, EXTENDED GLOBBING, AND OTHER ZSH-EXCLUSIVE FEATURES. ADDITIONALLY, ALL CODE MUST STRICTLY ADHERE TO THE DOCUMENTATION STANDARDS OUTLINED IN THIS DOCUMENT. FAILING TO UTILIZE ZSH-SPECIFIC FEATURES OR MAINTAIN PROPER DOCUMENTATION IS CONSIDERED A COMPLETE FAILURE OF THE IMPLEMENTATION.
  </the_most_important_rule>

  <!-- Directory naming conventions -->
  <rule id="directory-naming">
    <description>Directory naming convention</description>
    <pattern>kebab-case</pattern>
    <message>All directories should use kebab-case naming convention</message>
    <severity>error</severity>
    <!-- Exception for numbered directories in the ZZZ framework structure -->
    <exceptions>
      <exception>^\d+-[a-z]+</exception>
    </exceptions>
  </rule>
  
  <!-- File naming conventions -->
  <rule id="file-naming">
    <description>File naming convention</description>
    <pattern>kebab-case</pattern>
    <message>All files should use kebab-case naming convention</message>
    <severity>warning</severity>
    <exceptions>
      <exception>^\..*</exception> <!-- Dot files -->
      <exception>.*\.zsh$</exception> <!-- ZSH scripts -->
      <exception>.*\.md$</exception> <!-- Markdown files -->
      <exception>.*\.xml$</exception> <!-- XML files -->
      <exception>.*\.png$</exception> <!-- PNG files -->
    </exceptions>
  </rule>
  
  <!-- Code style rules -->
  <rule id="zsh-script-header">
    <description>ZSH script header requirement</description>
    <pattern>^#!/usr/bin/env zsh</pattern>
    <message>All ZSH scripts must start with #!/usr/bin/env zsh</message>
    <severity>error</severity>
  </rule>
  
  <!-- Shell startup cleanliness -->
  <rule id="clean-shell-startup">
    <description>Clean shell startup</description>
    <message>Shell startup must not produce any output</message>
    <severity>error</severity>
  </rule>
  
  <!-- Framework structure rules -->
  <rule id="framework-structure">
    <description>Framework structure</description>
    <message>The framework must maintain separation between interactive and non-interactive shell configurations</message>
    <severity>error</severity>
  </rule>

  <!-- ZSH Syntax Migration Rules -->
  <rule id="ZshSyntaxMigration">
    <description>Migrate shell scripts to use Zsh-specific syntax and idioms.</description>
    <patterns>
      <!-- Basic Syntax Conversions -->
      <pattern>
        <search>\$\{.*\}</search>
        <replace>${${1}}</replace>
        <description>Convert bash-style parameter expansion to zsh's syntax.</description>
      </pattern>
      <pattern>
        <search>\[.*\]</search>
        <replace>[[ ${1} ]]</replace>
        <description>Convert bash-style test conditions to zsh's syntax.</description>
      </pattern>
      <pattern>
        <search>typeset</search>
        <replace>typeset -g</replace>
        <description>Ensure global variable declarations.</description>
      </pattern>
      <pattern>
        <search>declare -a</search>
        <replace>typeset -ga</replace>
        <description>Convert bash array declarations to zsh's syntax.</description>
      </pattern>
      <pattern>
        <search>declare -A</search>
        <replace>typeset -gA</replace>
        <description>Convert bash associative array declarations to zsh's syntax.</description>
      </pattern>
      <pattern>
        <search>\$\((.*?)\)</search>
        <replace>$(( ${1} ))</replace>
        <description>Convert arithmetic expansion to zsh's syntax.</description>
      </pattern>
      <pattern>
        <search>export</search>
        <replace>typeset -gx</replace>
        <description>Convert bash export to zsh typeset -gx.</description>
      </pattern>
      <pattern>
        <search>echo</search>
        <replace>print -r --</replace>
        <description>Convert bash echo to zsh print -r --.</description>
      </pattern>
      <!-- Zsh-Specific Features and Idioms -->
      <pattern>
        <search>for i in \(\*.\)</search>
        <replace>for i in ${(f)${1}}</replace>
        <description>Use zsh's word splitting for globbing.</description>
      </pattern>
      <pattern>
        <search>if \[ -f ".*" \]</search>
        <replace>if [[ -f ${1} ]]</replace>
        <description>Use zsh's [[ ]] for file checks.</description>
      </pattern>
      <pattern>
        <search>if \[ -d ".*" \]</search>
        <replace>if [[ -d ${1} ]]</replace>
        <description>Use zsh's [[ ]] for directory checks.</description>
      </pattern>
      <pattern>
        <search>if \[ -z ".*" \]</search>
        <replace>if [[ -z ${1} ]]</replace>
        <description>Use zsh's [[ ]] for string length checks.</description>
      </pattern>
      <pattern>
        <search>if \[ -n ".*" \]</search>
        <replace>if [[ -n ${1} ]]</replace>
        <description>Use zsh's [[ ]] for string length checks.</description>
      </pattern>
      <pattern>
        <search>function (.*?)\(\) \{</search>
        <replace>function ${1}() {</replace>
        <description>Use zsh's function definition syntax.</description>
      </pattern>
      <pattern>
        <search>case \$\(.*?\) in</search>
        <replace>case ${1} in</replace>
        <description>Use zsh's case statement syntax.</description>
      </pattern>
      <pattern>
        <search>while \[.*?\]</search>
        <replace>while [[ ${1} ]]</replace>
        <description>Use zsh's [[ ]] for while loop conditions.</description>
      </pattern>
      <pattern>
        <search>until \[.*?\]</search>
        <replace>until [[ ${1} ]]</replace>
        <description>Use zsh's [[ ]] for until loop conditions.</description>
      </pattern>
      <pattern>
        <search>if \[.*?\]; then</search>
        <replace>if [[ ${1} ]]; then</replace>
        <description>Use zsh's [[ ]] for if statement conditions.</description>
      </pattern>
    </patterns>
  </rule>

  <!-- ZSH Best Practices -->
  <rule id="ZshBestPractices">
    <description>Apply Zsh best practices and style guidelines.</description>
    <guidelines>
      <guideline>
        <description>Use `typeset -g` for global variables.</description>
      </guideline>
      <guideline>
        <description>Use `local` for local variables within functions.</description>
      </guideline>
      <guideline>
        <description>Use `typeset -ga` for arrays and `typeset -gA` for associative arrays.</description>
      </guideline>
      <guideline>
        <description>Use `[[ ]]` for conditional expressions.</description>
      </guideline>
      <guideline>
        <description>Use `print -r --` for printing strings.</description>
      </guideline>
      <guideline>
        <description>Use consistent indentation (e.g., 2 spaces).</description>
      </guideline>
      <guideline>
        <description>Add comments to explain complex logic.</description>
      </guideline>
      <guideline>
        <description>Use meaningful variable names (e.g., `file_path` instead of `fp`).</description>
      </guideline>
      <guideline>
        <description>Avoid unnecessary use of external commands (use Zsh built-ins where possible).</description>
      </guideline>
      <guideline>
        <description>Use Zsh's built-in functions whenever possible.</description>
      </guideline>
      <guideline>
        <description>Handle errors gracefully (e.g., use `trap` for error handling).</description>
      </guideline>
      <guideline>
        <description>Use parameter expansion flags for efficient string manipulation.</description>
      </guideline>
    </guidelines>
  </rule>

  <!-- Mandatory Header and Footer -->
  <rule id="MandatoryHeaderFooter">
    <description>Ensure all Zsh files begin with a standardized header and end with a matching footer, including MARK tags.</description>
    <header><![CDATA[
#**************************************************************
# shellcheck shell=zsh
#**************************************************************
#                       MARK:<ZSH_FILE_HEADER>
#**************************************************************
#
#
#
#**************************************************************
#                       MARK:<PURPOSE />
#**************************************************************
# Environment variables
# Path configurations
# Global settings
# All shell types
#**************************************************************
    ]]></header>
    <footer><![CDATA[
#**************************************************************
#                       MARK:</ZSH_FILE_HEADER>
#**************************************************************
    ]]></footer>
    <patterns>
      <pattern>
        <search>^(?:#!\/bin\/zsh(?:\s+.*)?\n)?(.*?)(?:\Z|\z)</search>
        <replace>$1${header}$2${footer}</replace>
        <description>Handle shebang lines and file content comprehensively</description>
      </pattern>
      <pattern>
        <search>MARK:&lt;([^&gt;]+)&gt;(.*?)MARK:&lt;\/\1&gt;</search>
        <replace>MARK:&lt;$1&gt;$2MARK:&lt;/$1&gt;</replace>
        <description>Normalize MARK tags with proper nesting</description>
      </pattern>
      <pattern>
        <search>&lt;PURPOSE\s*?\/&gt;</search>
        <replace>&lt;PURPOSE /&gt;</replace>
        <description>Normalize empty PURPOSE tags</description>
      </pattern>
    </patterns>
  </rule>

  <!-- ZSH Parameter Expansion -->
  <rule id="ZshParameterExpansion">
    <description>Enforce consistent and efficient use of Zsh parameter expansion.</description>
    <patterns>
      <pattern>
        <search>\$\{(.*?)\}</search>
        <replace>${${1}}</replace>
        <description>Use Zsh parameter expansion consistently.</description>
      </pattern>
      <pattern>
        <search>\$\{(.*?)\#(.*?)\}</search>
        <replace>${${1}#${2}}</replace>
        <description>Use Zsh parameter expansion consistently.</description>
      </pattern>
      <pattern>
        <search>\$\{(.*?)\%(.*?)\}</search>
        <replace>${${1}%${2}}</replace>
        <description>Use Zsh parameter expansion consistently.</description>
      </pattern>
      <pattern>
        <search>\$\{(.*?)\#\#(.*?)\}</search>
        <replace>${${1}##${2}}</replace>
        <description>Use Zsh parameter expansion consistently.</description>
      </pattern>
      <pattern>
        <search>\$\{(.*?)\%\%(.*?)\}</search>
        <replace>${${1}%%${2}}</replace>
        <description>Use Zsh parameter expansion consistently.</description>
      </pattern>
    </patterns>
  </rule>

  <!-- ZSH Array Handling -->
  <rule id="ZshArrayHandling">
    <description>Enforce consistent and efficient use of Zsh arrays.</description>
    <patterns>
      <pattern>
        <search>local -a (.*) = \(.*\)</search>
        <replace>local -a ${1}=(${2})</replace>
        <description>Use concise array initialization.</description>
      </pattern>
      <pattern>
        <search>\[(.*?)\]</search>
        <replace>${1}</replace>
        <description>Use concise array indexing.</description>
      </pattern>
    </patterns>
  </rule>

  <!-- Framework Architecture Guidelines -->
  <rule id="FrameworkArchitecture">
    <description>Guidelines for the ZZZ Shell Framework architecture.</description>
    <guidelines>
      <guideline>
        <description>Initialize global variables only in zshenv.zsh</description>
      </guideline>
      <guideline>
        <description>Use the globally accessible logger module</description>
      </guideline>
      <guideline>
        <description>Use the zsource function instead of source or custom wrappers</description>
      </guideline>
      <guideline>
        <description>Use zdebug for debug messages to respect ZZZ_DEBUG setting</description>
      </guideline>
      <guideline>
        <description>Maintain separation between interactive and non-interactive shell configurations</description>
      </guideline>
      <guideline>
        <description>Non-interactive shells should only load essential modules</description>
      </guideline>
      <guideline>
        <description>Interactive-only configurations should be in zshrc.zsh</description>
      </guideline>
    </guidelines>
  </rule>

  <!-- Documentation Standards -->
  <rule id="DocumentationStandards">
    <description>Standards for documentation in the ZZZ Shell Framework.</description>
    <guidelines>
      <guideline>
        <description>Every line of code must have an explanatory comment (Hyper Comment Rule)</description>
      </guideline>
      <guideline>
        <description>All functions must have a description of their purpose, parameters, and return values</description>
      </guideline>
      <guideline>
        <description>All files must have a header with author, date, and purpose</description>
      </guideline>
      <guideline>
        <description>All modules must have a README.md file explaining their purpose and usage</description>
      </guideline>
      <guideline>
        <description>All changes must be documented in the CHANGELOG directory</description>
      </guideline>
    </guidelines>
  </rule>

  <!-- Error Handling -->
  <rule id="ErrorHandling">
    <description>Standards for error handling in the ZZZ Shell Framework.</description>
    <guidelines>
      <guideline>
        <description>Use setopt ERR_RETURN to exit functions on error</description>
      </guideline>
      <guideline>
        <description>Use setopt PIPE_FAIL to propagate pipeline errors</description>
      </guideline>
      <guideline>
        <description>Use setopt NO_UNSET to treat unset variables as errors</description>
      </guideline>
      <guideline>
        <description>Use trap to handle errors and cleanup resources</description>
      </guideline>
      <guideline>
        <description>Use the logger module for error reporting</description>
      </guideline>
    </guidelines>
  </rule>
</rules>