Added #307: MIS of Long Element Chain

docs/Design/SoftArchitecture/MG.tex

@@ -192,7 +192,7 @@ \section{Module Hierarchy} \label{SecMH}
 
 \begin{description}
 \item [\refstepcounter{mnum} \mthemnum \label{mHH}:] Hardware-Hiding Module
-\item ...
+\item [\refstepcounter{mnum} \mthemnum \label{mLEC}:] LongElementChainRefactorer Module
 \end{description}
 
 
@@ -209,7 +209,7 @@ \section{Module Hierarchy} \label{SecMH}
 \multirow{7}{0.3\textwidth}{Behaviour-Hiding Module} & ?\\
 & ?\\
 & ?\\
-& ?\\
+& LongElementChainRefactorer Module\\
 & ?\\
 & ?\\
 & ?\\ 
@@ -278,6 +278,21 @@ \subsection{Behaviour-Hiding Module}
 \item[Implemented By:] --
 \end{description}
 
+\subsubsection{Long Element Chain Module (\mref{mLEC})}
+
+% [Record, Library, Abstract Object, or Abstract Data Type]
+
+\begin{description}
+    \item[Secrets:] How to parse a given code file to its AST representation, traverse the 
+    AST tree to identify dictionary assignments, analyze the structure of nested dictionaries,
+     and flatten them. Additionally, it identifies all access calls associated with these dictionaries
+      in the source code and determines how to update them to reflect the new flattened structure.
+    \item[Services:] Detects nested dictionaries in the source code using AST parsing, simplifies their 
+    structure by flattening them, and updates all associated access calls throughout the file. This improves 
+    code readability, reduces complexity, and ensures correctness while maintaining the program's intended behavior.
+    \item[Implemented By:] EcoOptimizer
+\end{description}
+
 \subsubsection{Input Format Module (\mref{mInput})}
 
 \begin{description}

docs/Design/SoftDetailedDes/MIS.tex

@@ -227,8 +227,105 @@ \subsubsection{Local Functions}
   explicitly.  Even if they are implemented, they are not exported; they only
   have local scope.}
 
+
+\section{MIS of LongElementChainRefactorer}
+
+\subsection{Module}
+
+LongElementChainRefactorer is a module that refactors long element chains, specifically focusing on flattening nested dictionaries to improve readability, maintainability, and energy efficiency. The module uses a recursive flattening strategy while caching previously seen patterns for optimization.
+
+\subsection{Uses}
+
+\begin{itemize}
+    \item Uses \texttt{Smell} interface for data access
+    \item Inherits from \texttt{BaseRefactorer}
+\end{itemize}
+
+\subsection{Syntax}
+
+\subsubsection{Exported Constants}
+None
+
+\subsubsection{Exported Access Programs}
+
+\begin{center}
+\begin{tabular}{|p{3cm}|p{5cm}|p{2cm}|p{3cm}|}
+\hline
+\textbf{Name} & \textbf{In} & \textbf{Out} & \textbf{Exceptions} \\
+\hline
+\texttt{\_\_init\_\_} & \texttt{output\_dir: Path} & None & None \\
+\hline
+\texttt{refactor} & \texttt{file\_path: Path, pylint\_smell: Smell, initial\_emissions: float} & None & Logging exceptions \\
+\hline
+\end{tabular}
+\end{center}
+
+\subsection{Semantics}
+
+\subsubsection{State Variables}
+
+\begin{itemize}
+  \item \textbf{\_reference\_map}: Maps element chain references to their line numbers and corresponding values.
+\end{itemize}
+
+\subsubsection{Environment Variables}
+
+\begin{itemize}
+  \item \textbf{File system}: Used to read, write, and store temporary and refactored files.
+  \item \textbf{Logger}: Logs information during the refactoring process.
+\end{itemize}
+
+\subsubsection{Assumptions}
+
+\begin{itemize}
+  \item Input files are valid Python scripts.
+  \item Smells identified by \textbf{pylint\_smell} include valid line numbers.
+  \item Refactored code must pass the provided test suite.
+\end{itemize}
+
+\subsubsection{Access Routine Semantics}
+
+\paragraph{\texttt{\_\_init\_\_(output\_dir: Path)}}
+\begin{itemize}
+\item \textbf{Transition}: Initializes the refactorer with the specified output directory and sets up internal caching structures.
+\item \textbf{Output}: None.
+\item \textbf{Exception}: None.
+\end{itemize}
+
+\paragraph{\texttt{refactor(file\_path: Path, pylint\_smell: Smell, initial\_emissions: float)}}
+\begin{itemize}
+  \item \textbf{Transition}:
+    \begin{itemize}
+      \item Reads the file at \texttt{file\_path}.
+      \item Identifies nested dictionary chains for flattening.
+      \item Refactors the identified chain by flattening the dictionary and replacing its occurrences.
+      \item Writes the refactored code to a temporary file.
+\end{itemize}
+  \item \textbf{Output}: None. Refactored file is saved if improvements are validated.
+  \item \textbf{Exception}: Logs exceptions during file operations or refactoring.
+\end{itemize}
+
+\subsubsection{Local Functions}
+\begin{itemize}
+    \item \textbf{\_flatten\_dict(d: dict[str, Any], parent\_key: str = "")} \\
+    Recursively flattens a nested dictionary by combining keys with underscores.
+
+    \item \textbf{\_extract\_dict\_literal(node: ast.AST)} \\
+    Converts an Abstract Syntax Tree (AST) dictionary literal into a Python dictionary.
+
+    \item \textbf{\_find\_dict\_assignments(tree: ast.AST, name: str)} \\
+    Extracts dictionary assignments given the name of the dictionary from the AST and returns them as a dictionary.
+
+    \item \textbf{\_collect\_dict\_references(tree: ast.AST)} \\
+    Identifies and stores all dictionary access patterns in the `\_reference\_map`.
+
+    \item \textbf{\_generate\_flattened\_access(base\_var: str, access\_chain: list[str])} \\
+    Generates a flattened dictionary key string by combining elements of an access chain with underscores.
+\end{itemize}
+
 \newpage
 
+
 \bibliographystyle {plainnat}
 \bibliography {../../../refs/References}