@specs-feup/clava-misra 1.0.3 → 1.0.4

package/src/utils/FileUtils.ts

@@ -12,20 +12,62 @@ import path from "path";
  * @param fileJp - The file to validate.
  */
 export function isValidFile(fileJp: FileJp, jpType?: typeof Joinpoint, index?: number) : boolean | Joinpoint | undefined {
-    const programJp = fileJp.parent as Program;
-    let copyFile = ClavaJoinPoints.fileWithSource(`temp_misra_${fileJp.name}`, fileJp.code, fileJp.relativeFolderpath);
     let result: boolean | Joinpoint = true;
 
+    // Create a temporary copy of the file for validation
+    const programJp = fileJp.parent as Program;
+    let copyFile = ClavaJoinPoints.fileWithSource(`temp_misra_${fileJp.name}`, fileJp.code, fileJp.relativeFolderpath);
     copyFile = programJp.addFile(copyFile) as FileJp;
+
     try {
         const rebuiltFile = copyFile.rebuild();
-        const fileToRemove = Query.searchFrom(programJp, FileJp, {filepath: rebuiltFile.filepath}).first();
-        if (jpType && index) {
+        if (jpType && index) { // If requested, return a specific join point inside the rebuilt file
             result = Query.searchFrom(rebuiltFile, jpType).get()[index];
         }
+        
+        // Remove the temporary file
+        const fileToRemove = Query.searchFrom(programJp, FileJp, {filepath: rebuiltFile.filepath}).first();
         fileToRemove?.detach();
         return result;
     } catch(error) {
+        // On rebuild failure, delete copy file and return false
+        copyFile.detach();
+        return false;
+    }
+}
+
+/**
+ * Checks if the rebuilt version of the file compiles and if the provided call is no longer implicit.
+ * 
+ * @param fileJp The file to analyze
+ * @param funcName The function name to search the call
+ * @param callIndex The index of the call 
+ */
+export function isValidFileWithExplicitCall(fileJp: FileJp, funcName: string, callIndex: number, checkNumParams: boolean = false): boolean {
+    const programJp = fileJp.parent as Program;
+
+    // Create a temporary copy of the file for validation
+    let copyFile = ClavaJoinPoints.fileWithSource(`temp_misra_${fileJp.name}`, fileJp.code, fileJp.relativeFolderpath);
+    copyFile = programJp.addFile(copyFile) as FileJp;
+
+    try {
+        // Rebuild the file to check validity
+        const rebuiltFile = copyFile.rebuild();
+        const fileToRemove = Query.searchFrom(programJp, FileJp, {filepath: rebuiltFile.filepath}).first() as FileJp;
+
+        // Locate the function call and check if it is implicit
+        const callJp = Query.searchFrom(fileToRemove, Call, {name: funcName}).get().at(callIndex);
+        let isExplicitCall = callJp !== undefined && !isCallToImplicitFunction(callJp);
+        
+        if (checkNumParams && isExplicitCall) {
+            isExplicitCall = isExplicitCall && callJp!.args.length === callJp!.directCallee.params.length;
+        }
+
+        // Remove the temporary file
+        fileToRemove?.detach();
+        return isExplicitCall;
+
+    } catch(error) { // On rebuild failure, delete copy file and return false
         copyFile.detach();
         return false;
     }
@@ -56,7 +98,7 @@ export function removeIncludeFromFile(includeName: string, fileJp: FileJp) {
  * Returns all files in the program that include a given header file using the `#include` directive
  *
  * @param headerName - The name of the header file to search for
- * @returns A array of files that include the specified header
+ * @returns An array of files that include the specified header
  */
 export function findFilesReferencingHeader(headerName: string): FileJp[] {
     return Query.search(FileJp, (jp) =>{ return getIncludesOfFile(jp).has(headerName)}).get();
@@ -79,37 +121,11 @@ export function getFilesWithCallToImplicitFunction(programJp: Program): FileJp[]
 } 
 
 /**
- * Checks if the rebuilt version of the file compiles and if the provided call is no longer implicit.
- * 
- * @param fileJp The file to analyze
- * @param funcName The function name to search the call
- * @param callIndex The index of the call 
- */
-export function isValidFileWithExplicitCall(fileJp: FileJp, funcName: string, callIndex: number, checkNumParams: boolean = false): boolean {
-    const programJp = fileJp.parent as Program;
-    let copyFile = ClavaJoinPoints.fileWithSource(`temp_misra_${fileJp.name}`, fileJp.code, fileJp.relativeFolderpath);
-
-    copyFile = programJp.addFile(copyFile) as FileJp;
-    try {
-        const rebuiltFile = copyFile.rebuild();
-        const fileToRemove = Query.searchFrom(programJp, FileJp, {filepath: rebuiltFile.filepath}).first() as FileJp;
-        const callJp = Query.searchFrom(fileToRemove, Call, {name: funcName}).get().at(callIndex);
-        let isExplicitCall = callJp !== undefined && !isCallToImplicitFunction(callJp);
-        
-        if (checkNumParams && isExplicitCall) {
-            isExplicitCall = isExplicitCall && callJp!.args.length === callJp!.directCallee.params.length;
-        }
-        fileToRemove?.detach();
-        return isExplicitCall;
-
-    } catch(error) {
-        copyFile.detach();
-        return false;
-    }
-}
-
-/**
+ * Inserts an extern declaration of the given function into the file.
  * 
+ * @param fileJp The file to modify.
+ * @param functionJp The function to declare as extern.
+ * @returns The inserted join point, or undefined if the function has no external linkage.
  */
 export function addExternFunctionDecl(fileJp: FileJp, functionJp: FunctionJp): Joinpoint | undefined {
     if (!isExternalLinkageIdentifier(functionJp)) {
@@ -128,14 +144,26 @@ export function addExternFunctionDecl(fileJp: FileJp, functionJp: FunctionJp): J
     return newExternStmt;
 }
 
-export function getExternFunctionDecls(fileJp: FileJp) {
+/**
+ * Returns all extern function declarations in the given file
+ * @param fileJp The file join point
+ * @returns An array of functions declared with 'extern'
+ */
+export function getExternFunctionDecls(fileJp: FileJp): FunctionJp[] {
     return Query.searchFrom(fileJp, FunctionJp, {storageClass: StorageClass.EXTERN}).get();
 }
 
-export function getCallsToLibrary(fileJp: FileJp, libraryFile: string, functionNames: Set<string> = new Set()): Call[] {
+/**
+ * Returns function calls from a file that are defined in the provided library header. Optionally filters by function names.
+ * 
+ * @param fileJp The file join point
+ * @param libraryName Header filename
+ * @param functionNames Optional list of function names to filter
+ */
+export function getCallsToLibrary(fileJp: FileJp, libraryName: string, functionNames: Set<string> = new Set()): Call[] {
     return Query.searchFrom(fileJp, Call, (callJp) =>
         callJp.function?.isInSystemHeader &&
-        callJp.function?.filepath.endsWith(libraryFile) &&
+        callJp.function?.filepath.endsWith(libraryName) &&
         (functionNames.size === 0 || functionNames.has(callJp.name))
     ).get();
 }

package/src/utils/FunctionUtils.ts

@@ -1,4 +1,4 @@
-import { Param, Joinpoint, Varref, FunctionJp, StorageClass, GotoStmt, LabelStmt, FileJp, Call, VariableArrayType } from "@specs-feup/clava/api/Joinpoints.js";
+import { Param, Varref, FunctionJp, StorageClass, GotoStmt, LabelStmt, FileJp, Call, VariableArrayType } from "@specs-feup/clava/api/Joinpoints.js";
 import Query from "@specs-feup/lara/api/weaver/Query.js";
 import { findFilesReferencingHeader } from "./FileUtils.js";
 import { hasDefinedType } from "./JoinpointUtils.js";
@@ -38,12 +38,25 @@ export function getParamReferences($param: Param, functionJp: FunctionJp): Varre
     return Array.from(new Map([...directRefs, ...refsInVLAFields as Varref[]].map(ref => [ref.ast, ref])).values());
 }
 
+/**
+ * Gets all label statements in the given function that are never referenced
+ * @param func The function to analyze
+ * @returns An array of unused labels statements
+ */
 export function getUnusedLabels(func: FunctionJp): LabelStmt[] {
     return Query.searchFrom(func, LabelStmt).get().filter(label => 
         Query.searchFrom(func, GotoStmt, { label: jp => jp.astId === label.decl.astId }).get().length === 0
     );
 }
 
+/**
+ * Returns the first function definition matching the given name and file path suffix
+ *
+ * @param functionName Name of the function
+ * @param pathSuffix File path suffix
+ * @returns The function definition, or undefined if not found
+ */
+
 export function findFunctionDef(functionName: string, pathSuffix: string) {
     const funcDefs = Query.search(FunctionJp, (func) => {
                 try {
@@ -55,11 +68,21 @@ export function findFunctionDef(functionName: string, pathSuffix: string) {
     return funcDefs.length > 0 ? funcDefs[0] : undefined;
 }
 
+/**
+ * Finds extern declarations for the given function
+ * @param functionJp The function join point
+ * @returns List of extern function declarations
+ */
 export function findExternalFunctionDecl(functionJp: FunctionJp): FunctionJp[] {
     return functionJp.declarationJps
             .filter((declJp) => declJp.storageClass === StorageClass.EXTERN);
 }
 
+/**
+ * Checks if the given function is called anywhere in the project
+ * @param functionJp The function to evaluate
+ * @returns True if the function is used, false otherwise
+ */
 export function isFunctionUsed(functionJp: FunctionJp): boolean {
     const fileJp = functionJp.getAncestor("file") as FileJp;
     let referencingFiles: FileJp[];
@@ -71,5 +94,4 @@ export function isFunctionUsed(functionJp: FunctionJp): boolean {
         referencingFiles = [fileJp];
     }
     return referencingFiles.some(fileJp => Query.searchFrom(fileJp, Call, {name: functionJp.name, directCallee: (jp) => jp?.ast === functionJp.ast}).get().length > 0)
-}
-
+}

package/src/utils/IdentifierUtils.ts

@@ -1,7 +1,13 @@
 import { Joinpoint, Vardecl, StorageClass, FunctionJp, TypedefDecl, LabelStmt, NamedDecl } from "@specs-feup/clava/api/Joinpoints.js";
-import { compareLocation, getFileLocation, isTagDecl } from "./JoinpointUtils.js";
+import { compareLocation, isTagDecl } from "./JoinpointUtils.js";
 import { findDuplicateVarDefinition, findExternalVarRefs, isSameVarDecl } from "./VarUtils.js";
 
+/**
+ * Checks if the given joinpoint is an identifier declaration (variable, function, typedef, label, or tag)
+ * 
+ * @param $jp The joinpoint to evaluate
+ * @returns True if the join point is an identifier declaration, false otherwise
+ */
 export function isIdentifierDecl($jp: Joinpoint): boolean {
     return  ($jp instanceof Vardecl && $jp.storageClass !== StorageClass.EXTERN) || 
             ($jp instanceof FunctionJp && $jp.isImplementation) || 
@@ -10,6 +16,11 @@ export function isIdentifierDecl($jp: Joinpoint): boolean {
             isTagDecl($jp);
 }
 
+/**
+ * Retrieves the name of the given joinpoint
+ * @param $jp The joinpoint to evaluate
+ * @returns The name of the identifier, or undefined if the join point does not represent an identifier
+ */
 export function getIdentifierName($jp: Joinpoint): string | undefined {
     if ($jp instanceof NamedDecl) {
         return $jp.name;
@@ -19,6 +30,12 @@ export function getIdentifierName($jp: Joinpoint): string | undefined {
     return undefined;
 }
 
+/**
+ * Checks if two joinpoints represent different identifiers with the same name
+ * @param identifier1 The first joinpoint to evaluate
+ * @param identifier2 The second joinpoint to evaluate
+ * @returns True if names match and the nodes differ, otherwise returns false
+ */
 export function areIdentifierNamesEqual(identifier1: Joinpoint, identifier2: Joinpoint) {
     const name1 = getIdentifierName(identifier1);
     const name2 = getIdentifierName(identifier2);
@@ -27,21 +44,25 @@ export function areIdentifierNamesEqual(identifier1: Joinpoint, identifier2: Joi
     return identifier1.ast !== identifier2.ast && name1 === name2;
 }
 
+/**
+ * Updates the name of an identifier joinpoint
+ * @param $jp The joinpoint to rename
+ * @param newName the new identifier name
+ * @returns True if renaming was successful, false otherwise
+ */
 export function renameIdentifier($jp: Joinpoint, newName: string): boolean {
     if ($jp instanceof LabelStmt) {
         $jp.decl.setName(newName);
     } 
     else if ($jp instanceof Vardecl) {
-        if (!isExternalLinkageIdentifier($jp)) {
-            $jp.setName(newName);
-        } else {
-            const externalRefs = findExternalVarRefs($jp);
-            const duplicateDefs = findDuplicateVarDefinition($jp);
-            
-            $jp.setName(newName);
+        const externalRefs = findExternalVarRefs($jp);
+        const duplicateDefs = findDuplicateVarDefinition($jp);
+        
+        $jp.setName(newName);
+        if (isExternalLinkageIdentifier($jp)) { 
             externalRefs.forEach((varRef) => varRef.setName(newName));
-            duplicateDefs.forEach((defJp) => defJp.setName(newName));            
-        }
+            duplicateDefs.forEach((defJp) => defJp.setName(newName));   
+        }         
     } 
     else if ($jp instanceof NamedDecl) {
         $jp.setName(newName);
@@ -49,6 +70,12 @@ export function renameIdentifier($jp: Joinpoint, newName: string): boolean {
     return true;
 }
 
+/**
+ * Checks if a given joinpoint represents an identifier with external linkage
+ * 
+ * @param $jp The joinpoint to evaluate
+ * @returns  True if the joinpoint has external linkage, false otherwise
+ */
 export function isExternalLinkageIdentifier($jp: Joinpoint): boolean {
     if (!($jp instanceof FunctionJp || $jp instanceof Vardecl)) {
         return false;
@@ -60,6 +87,12 @@ export function isExternalLinkageIdentifier($jp: Joinpoint): boolean {
     return result;
 }
 
+/**
+ * Checks if a given joinpoint represents an identifier with internal linkage
+ * 
+ * @param $jp The joinpoint to evaluate
+ * @returns  True if the joinpoint has internal linkage, false otherwise
+ */
 export function isInternalLinkageIdentifier($jp: Joinpoint): boolean {
     if (!($jp instanceof FunctionJp || $jp instanceof Vardecl)) {
         return false;
@@ -72,10 +105,25 @@ export function isInternalLinkageIdentifier($jp: Joinpoint): boolean {
     return result;
 }
 
+/**
+ * Determines if an identifier is duplicated in a collection of join points
+ *
+ * @param $jp The identifier to evaluate
+ * @param $others Other join points to compare with
+ * @returns True if a duplicate exists, false otherwise
+ */
 export function isIdentifierDuplicated($jp: Joinpoint, $others: Joinpoint[]) {
     return $others.some((identifier) => identifier.astId !== $jp.astId && !isSameVarDecl($jp, identifier) && areIdentifierNamesEqual($jp, identifier));
 }
 
+/**
+ * Checks if another identifier with the same name is declared before the given joinpoint
+ *
+ * @param $jp The identifier join point to check
+ * @param $others The list of other identifiers to compare with
+ * @returns True if a matching identifier is declared earlier, false otherwise.
+ */
+
 export function isIdentifierNameDeclaredBefore($jp: Joinpoint, $others: Joinpoint[]) {
     return $others.some((identifier) =>  {
         return identifier.astId !== $jp.astId && !isSameVarDecl($jp, identifier) && compareLocation(identifier, $jp) < 0 && areIdentifierNamesEqual(identifier, $jp)

package/src/utils/JoinpointUtils.ts

@@ -30,10 +30,20 @@ export function getBaseType($jp: Joinpoint): Type | undefined {
     return jpType;
 }
 
-export function getFilepath($jp: Joinpoint) {
+/**
+ * Gets the file path of the given join point.
+ * @param $jp The join point
+ * @returns The file path string
+ */
+export function getFilepath($jp: Joinpoint): string {
     return $jp instanceof Include ? $jp.parent.filepath : $jp.filepath;
 }
 
+/**
+ * Returns the exact location of a given join point
+ * @param $jp The joinpoint to evaluate
+ * @returns A location string containing the filepath, line and column in the format "filepath@line:column"
+ */
 export function getFileLocation($jp: Joinpoint) {
     if ($jp instanceof Include && $jp.line === undefined) {
         return `${$jp.parent?.filepath}`;
@@ -41,6 +51,13 @@ export function getFileLocation($jp: Joinpoint) {
     return `${$jp.filepath}@${$jp.line}:${$jp.column}`
 }
 
+/**
+ * Orders two join points by their source location: filepath, line, and column
+ *
+ * @param $jp1 The first join point
+ * @param $jp2 The second join point
+ * @returns  A negative value if $jp1 comes before $jp2, positive if after, or 0 if equal.
+ */
 export function compareLocation($jp1: Joinpoint, $jp2: Joinpoint): number {
     const filepath1 = getFilepath($jp1), filepath2 = getFilepath($jp2);
     

package/src/utils/ProgramUtils.ts

@@ -1,14 +1,16 @@
-import { Vardecl, FunctionJp, Program, LabelStmt, NamedDecl, StorageClass } from "@specs-feup/clava/api/Joinpoints.js";
+import { Vardecl, FunctionJp, LabelStmt, NamedDecl, StorageClass } from "@specs-feup/clava/api/Joinpoints.js";
 import Query from "@specs-feup/lara/api/weaver/Query.js";
 import { isExternalLinkageIdentifier, isIdentifierDecl, isInternalLinkageIdentifier } from "./IdentifierUtils.js";
 
-
 let cachedInternalLinkageIdentifiers: (FunctionJp | Vardecl)[] | null = null;
 let cachedExternalLinkageIdentifiers: (FunctionJp | Vardecl)[] | null = null;
 let cachedExternalLinkageVars: (Vardecl)[] | null = null;
 let cachedExternalVarRefs: (Vardecl)[] | null = null;
 let cachedIdentifierDecls: any[] | null = null;
 
+/**
+ * Clears all cached identifiers and variable references
+ */
 export function resetCaches() {
     cachedInternalLinkageIdentifiers = null;
     cachedExternalLinkageIdentifiers = null;
@@ -17,6 +19,9 @@ export function resetCaches() {
     cachedIdentifierDecls = null;
 }
 
+/**
+ * Clears the cache of external variable references
+ */
 export function resetExternalVarRefs() {
     cachedExternalVarRefs = null;
 }
@@ -24,7 +29,8 @@ export function resetExternalVarRefs() {
 /**
  * Retrieves all variables and functions that are eligible for `extern` linkage, i.e., 
  * elements with storage classes that are not `STATIC` or `EXTERN`
- * @returns Array of functions and variables that can be declared as external
+ *
+ *  @returns Array of functions and variables that can be declared as external
  */
 export function getExternalLinkageIdentifiers(): (FunctionJp | Vardecl)[] {
     if (cachedExternalLinkageIdentifiers !== null) {
@@ -41,6 +47,11 @@ export function getExternalLinkageIdentifiers(): (FunctionJp | Vardecl)[] {
     return cachedExternalLinkageIdentifiers;
 }
 
+/**
+ * Gets identifiers with internal linkage
+ * 
+ * @returns List of functions and variable declarations with internal linkage
+ */
 export function getInternalLinkageIdentifiers(): (FunctionJp | Vardecl)[] {
     if (cachedInternalLinkageIdentifiers !== null) {
         return cachedInternalLinkageIdentifiers;
@@ -55,6 +66,11 @@ export function getInternalLinkageIdentifiers(): (FunctionJp | Vardecl)[] {
     return cachedInternalLinkageIdentifiers;
 }
 
+/**
+ * Gets identifiers with external linkage
+ * 
+ * @returns List of functions and variable declarations with external linkage
+ */
 export function getExternalLinkageVars(): Vardecl[] {
     if (cachedExternalLinkageVars != null) {
         return cachedExternalLinkageVars;
@@ -63,6 +79,11 @@ export function getExternalLinkageVars(): Vardecl[] {
     return cachedExternalLinkageVars;
 }
 
+/**
+ * Gets all variable declared with 'extern'
+ * 
+ * @returns List of variable declarations with extern storage class
+ */
 export function getExternalVarRefs(): Vardecl[] {
     if (cachedExternalVarRefs !== null) {
         return cachedExternalVarRefs;
@@ -71,6 +92,9 @@ export function getExternalVarRefs(): Vardecl[] {
     return cachedExternalVarRefs;
 }
 
+/**
+ * Gets all named declarations and labels
+ */
 export function getIdentifierDecls(): any[] {
     if (cachedIdentifierDecls !== null) {
         return cachedIdentifierDecls;

package/src/utils/TypeDeclUtils.ts

@@ -29,7 +29,6 @@ export function hasTypeDefDecl($jp: Joinpoint): boolean {
     return getTypeDefDecl($jp) !== undefined;
 }
 
-
 /**
  * Checks if a given joinpoint uses the specified typedef declaration.
  * @param jp - The joinpoint to check

package/src/utils/VarUtils.ts

@@ -20,7 +20,8 @@ export function getVolatileVarRefs($jp: Joinpoint): Varref[] {
 }
 
 /**
- * Retrieves all external references of the given variable.
+ * Retrieves all external references of the given variable
+ * 
  * @param $varDecl variable to match by name.
  * @returns Array of external references with the same name as the given variable.
  */
@@ -28,6 +29,12 @@ export function findExternalVarRefs($varDecl: Vardecl): Vardecl[] {
     return getExternalVarRefs().filter(ref => ref.name === $varDecl.name);
 }
 
+/**
+ * Identifies functions in the same file that reference the specified variable declaration
+ *
+ * @param $jp The variable declaration
+ * @returns An array of functions that reference the variable
+ */
 export function findReferencingFunctions($jp: Vardecl): FunctionJp[] {
     const fileJp = $jp.getAncestor("file");
     const functionsJp = Query.searchFrom(fileJp, FunctionJp).get();
@@ -38,10 +45,23 @@ export function findReferencingFunctions($jp: Vardecl): FunctionJp[] {
         );
 }
 
+/**
+ * Finds duplicate definitions of the given variable declaration among external linkage variables
+ *
+ * @param $jp The variable declaration to evaluate
+ * @returns An array of variable declarations representing duplicates
+ */
 export function findDuplicateVarDefinition($jp: Vardecl): Vardecl[] {
     return getExternalLinkageVars().filter((varDeclJp) => varDeclJp.astId !== $jp.astId && isSameVarDecl(varDeclJp, $jp));   
 }
 
+/**
+ * Checks whether two joinpoints represent the same variable declaration by comparing identifier name, type, and external linkage
+ *
+ * @param $jp1 The first join point
+ * @param $jp2 The second join point
+ * @returns True if both are equivalent external variable declarations, false otherwise
+ */
 export function isSameVarDecl($jp1: Joinpoint, $jp2: Joinpoint): boolean {
     return $jp1 instanceof Vardecl && $jp2 instanceof Vardecl &&
             isExternalLinkageIdentifier($jp1) && isExternalLinkageIdentifier($jp2) &&
@@ -49,12 +69,25 @@ export function isSameVarDecl($jp1: Joinpoint, $jp2: Joinpoint): boolean {
 		    $jp1.type.code === $jp2.type.code
 }
 
+/**
+ * Checks if the given variable has multiple external linkage declarations across different files
+ *
+ * @param $jp The variable declaration to evaluate
+ * @returns True if multiple external declarations exist, false otherwise
+ */
+
 export function hasMultipleExternalLinkDeclarations($jp: Vardecl): boolean {
     return getExternalLinkageIdentifiers().some(identifier => 
         isSameVarDecl(identifier, $jp) && identifier.getAncestor("file").ast !== $jp.getAncestor("file").ast
     );
 }
 
+/**
+ * Checks whether the given variable declaration is used in its file or in files that include its header.
+ *
+ * @param varDecl The variable declaration to check
+ * @returns True if the variable is referenced, false otherwise
+ */
 export function isVarUsed(varDecl: Vardecl): boolean {
     const fileJp = varDecl.getAncestor("file") as FileJp;
     let referencingFiles: FileJp[];
@@ -65,6 +98,5 @@ export function isVarUsed(varDecl: Vardecl): boolean {
     } else {
         referencingFiles = [fileJp];
     }
-
     return referencingFiles.some(fileJp => Query.searchFrom(fileJp, Varref, {name: varDecl.name, decl: (declJp) => declJp?.astId === varDecl.astId}).get().length > 0)
 }