@specs-feup/clava-misra 1.0.2 → 1.0.4

package/src/tests/utils.ts

@@ -4,15 +4,38 @@ import ClavaJoinPoints from "@specs-feup/clava/api/clava/ClavaJoinPoints.js";
 import { FileJp, Program } from "@specs-feup/clava/api/Joinpoints.js";
 import Query from "@specs-feup/lara/api/weaver/Query.js";
 import * as os from 'os';
+import { resetCaches } from "../utils/ProgramUtils.js";
+
+export function countMISRAErrors(): number;
+export function countMISRAErrors(ruleID: string): number;
+export function countMISRAErrors(startingPoint: FileJp | Program): number;
+export function countMISRAErrors(startingPoint: FileJp | Program, ruleID: string): number;
+
+export function countMISRAErrors(arg1?: FileJp | Program | string, arg2?: string): number {
+  let startingPoint: FileJp | Program;
+  let ruleID: string | undefined;
+
+  if (typeof arg1 === "string") {
+    ruleID = arg1;
+    startingPoint = Query.root() as Program;
+  } else {
+    startingPoint = arg1 ?? (Query.root() as Program);
+    ruleID = arg2;
+  }
 
-export function countMISRAErrors(startingPoint: FileJp | Program = Query.root() as Program): number {
   MISRATool.checkCompliance(startingPoint);
-  return MISRATool.getErrorCount();
+  
+  return ruleID ? 
+    MISRATool.context.errors.filter(error => error.ruleID === ruleID).length :
+    MISRATool.getErrorCount();
 }
 
-export function countErrorsAfterCorrection(configPath?: string): number {
-  MISRATool.applyCorrections(configPath);
-  return MISRATool.getActiveErrorCount();
+export function countErrorsAfterCorrection(ruleID?: string): number {
+  MISRATool.correctViolations();
+
+  return ruleID ? 
+    MISRATool.context.activeErrors.filter(error => error.ruleID === ruleID).length :
+    MISRATool.getActiveErrorCount();
 }
 
 export interface TestFile {
@@ -21,11 +44,13 @@ export interface TestFile {
     path?: string
 }
 
-export function registerSourceCode(files: TestFile[]): void {
+export function registerSourceCode(files: TestFile[], configPath?: string): void {
     beforeEach(() => {
-      const dataStore = Clava.getData();
+      resetCaches();
 
+      const dataStore = Clava.getData();
       dataStore.setStandard(process.env.STD_VERSION!);
+      dataStore.put("argv", configPath ? `config=${configPath}` : undefined);
 
       // If running on macOS, change libcCxxMode
       if (os.platform() === 'darwin') {

package/src/utils/CallUtils.ts

@@ -0,0 +1,37 @@
+import { Call, FileJp, FunctionJp, Varref } from "@specs-feup/clava/api/Joinpoints.js";
+import Query from "@specs-feup/lara/api/weaver/Query.js";
+
+/**
+ * Checks if the given joinpoint represents a call to an implicit function.
+ *
+ * @param callJp The call join point to analyze
+ */
+export function isCallToImplicitFunction(callJp: Call): boolean {
+    if ( callJp.function?.isInSystemHeader) { // Call to system header function
+        return false;
+    } 
+
+    const varrefs = Query.searchFrom(callJp, Varref, {isFunctionCall: false}).get().map(varRef => varRef.astId);
+    const args = new Set(callJp.argList.flatMap(arg => Query.searchFromInclusive(arg, Varref).get().map(varRef => varRef.astId)));
+    if (varrefs.length > 0 && !args.has(varrefs[0])) { // Call using function pointer
+        return false;
+    }
+    
+    const directCallee = callJp.directCallee;
+    if (directCallee === undefined) return true;
+    
+    const fileJp = directCallee.getAncestor("file");
+    if (fileJp === undefined) return true;
+
+    return Query.searchFrom(fileJp, FunctionJp, {name: callJp.name}).get().length === 0;
+}
+
+/**
+ * Computes the index of a call in a file
+ * @param fileJp The file to search in
+ * @param callJp The call to find
+ * @returns The index of the call or -1 if not found 
+ */
+export function getCallIndex(fileJp: FileJp, callJp: Call): number {
+    return Query.searchFrom(fileJp, Call, { name: callJp.name }).get().findIndex(c => c.equals(callJp));
+}

package/src/utils/CommentUtils.ts

@@ -0,0 +1,29 @@
+import { Joinpoint, WrapperStmt, Comment } from "@specs-feup/clava/api/Joinpoints.js";
+
+/**
+ * Checks if the comment is an inline comment
+ * @param $comment - The comment to check
+ * @returns Returns true if it's an inline comment, otherwise returns false
+ */
+export function isInlineComment($comment: Comment): boolean {
+    return $comment.astName === "InlineComment";
+}
+
+/**
+ * Retrieves all comments associated with a given joinpoint
+ * @param $jp - The joinpoint to retrieve comments from
+ * @returns Array of comments
+ */
+export function getComments($jp: Joinpoint): Comment[] {
+    return $jp instanceof Comment ? [$jp] : $jp.inlineComments;
+}
+
+/**
+ * Checks if a given join point is a comment statement
+ *
+ * @param $jp The join point to check
+ * @returns Returns true if the given join point is a comment statement, otherwise false
+ */
+export function isCommentStmt($jp: Joinpoint): boolean {
+    return $jp instanceof WrapperStmt && $jp.kind === "comment";
+}

package/src/utils/FileUtils.ts

@@ -0,0 +1,169 @@
+import ClavaJoinPoints from "@specs-feup/clava/api/clava/ClavaJoinPoints.js";
+import { FileJp, Program, Include, Call, FunctionJp, Joinpoint, StorageClass } from "@specs-feup/clava/api/Joinpoints.js";
+import Query from "@specs-feup/lara/api/weaver/Query.js";
+import { isCallToImplicitFunction } from "./CallUtils.js";
+import { isExternalLinkageIdentifier } from "./IdentifierUtils.js";
+import path from "path";
+
+/**
+ * Checks if a file compiles correctly after adding a statement by rebuilding it.
+ * If rebuilding fails, the file is considered invalid with the new statement.
+ * 
+ * @param fileJp - The file to validate.
+ */
+export function isValidFile(fileJp: FileJp, jpType?: typeof Joinpoint, index?: number) : boolean | Joinpoint | undefined {
+    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();
+        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;
+    }
+}
+
+/**
+ * Retrieves the list of header files included in the given file
+ *
+ * @param fileJp The file join point
+ * @returns An array of strings with the names of the includes
+ */
+export function getIncludesOfFile(fileJp: FileJp): Set<string> {
+    return new Set(fileJp.includes.map(includeJp => includeJp.isAngled ? includeJp.name : path.basename(includeJp.name)));
+}
+
+/**
+ * Removes a specific include directive from the given file, if it exists
+ *
+ * @param includeName The name of the include to remove 
+ * @param fileJp The file from which the include should be removed
+ */
+export function removeIncludeFromFile(includeName: string, fileJp: FileJp) {
+    const include = Query.searchFrom(fileJp, Include, {name: includeName}).first();
+    include?.detach();
+}
+
+/**
+ * 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 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();
+}
+
+/**
+ * Returns all files in the program that contain at least one call to an implicit function
+ *
+ * @param programJp - The program to analyze
+ * @returns A list of files with implicit function calls
+ */
+export function getFilesWithCallToImplicitFunction(programJp: Program): FileJp[] {
+    const files = Query.searchFrom(programJp, FileJp).get();
+    return files.filter(
+      (fileJp) =>
+        Query.searchFrom(fileJp, Call, (callJp) =>
+          isCallToImplicitFunction(callJp)
+        ).get().length > 0
+    );
+} 
+
+/**
+ * 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)) {
+        return undefined;
+    }
+
+    let childAfterExtern: Joinpoint = fileJp.firstChild;
+    
+    while(childAfterExtern instanceof Include) {
+        childAfterExtern = childAfterExtern.siblingsRight[0];
+    }
+
+    const externStr = `extern ${functionJp.getDeclaration(true)};`;
+    const externStmt = ClavaJoinPoints.stmtLiteral(externStr);
+    const newExternStmt = childAfterExtern.insertBefore(externStmt);
+    return newExternStmt;
+}
+
+/**
+ * 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();
+}
+
+/**
+ * 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(libraryName) &&
+        (functionNames.size === 0 || functionNames.has(callJp.name))
+    ).get();
+}

package/src/utils/FunctionUtils.ts

@@ -0,0 +1,97 @@
+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";
+
+/**
+ * Gets direct references to a parameter within a function
+ * @param $param Parameter to find references for
+ * @param functionJp Function joinpoint to search in
+ */
+export function getDirectParamReferences($param: Param, functionJp: FunctionJp): Varref[] {
+    return Query.searchFrom(functionJp, Varref, (ref) => { return ref.decl && ref.decl.astId === $param.astId}).get();
+}
+
+/**
+ * Gets variable references to a parameter inside Variable-Length Array (VLA) fields
+ * @param $param Parameter to find references for
+ * @param functionJp Function joinpoint to search in 
+ */
+export function getVLAFieldParamReferences($param: Param, functionJp: FunctionJp): Varref[] { 
+    const vlaJoinpoints = functionJp.descendants.filter(jp => hasDefinedType(jp) && jp.type instanceof VariableArrayType);
+    const fieldsInVLAs = vlaJoinpoints.flatMap(jp => jp.jpFields(true).flatMap(field => [field, ...field.descendants]));
+
+    return fieldsInVLAs.filter(field => field instanceof Varref && field.decl?.astId === $param.astId) as Varref[];
+}
+
+/**
+ * Gets all unique variable references to a parameter in a function.
+ * @param $param Parameter to find references for
+ * @param functionJp Function joinpoint to search in 
+ * @returns Array of unique Varref references
+ */
+export function getParamReferences($param: Param, functionJp: FunctionJp): Varref[] {
+    const directRefs = getDirectParamReferences($param, functionJp);
+    const refsInVLAFields = getVLAFieldParamReferences($param, functionJp);
+    
+    // Remove duplicated nodes
+    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 {
+                    return func.name === functionName && func.isImplementation && func.filepath.endsWith(pathSuffix)
+                } catch (error) {
+                    return false;
+                }
+            }).get();
+    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[];
+
+    if (fileJp.isHeader) {
+        const filesWithInclude = findFilesReferencingHeader(fileJp.name);
+        referencingFiles = [fileJp, ...filesWithInclude];
+    } else {
+        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

@@ -0,0 +1,142 @@
+import { Joinpoint, Vardecl, StorageClass, FunctionJp, TypedefDecl, LabelStmt, NamedDecl } from "@specs-feup/clava/api/Joinpoints.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) || 
+            $jp instanceof TypedefDecl ||
+            $jp instanceof LabelStmt ||
+            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;
+    } else if ($jp instanceof LabelStmt) {
+        return $jp.decl.name;
+    } 
+    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);
+
+    if (!name1 || !name2) return false; 
+    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) {
+        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));   
+        }         
+    } 
+    else if ($jp instanceof NamedDecl) {
+        $jp.setName(newName);
+    } 
+    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;
+    }
+    let result = $jp.storageClass !== StorageClass.STATIC && $jp.storageClass !== StorageClass.EXTERN && $jp.getAncestor("function") === undefined;
+    if ($jp instanceof FunctionJp) {
+        result = result && $jp.isImplementation;
+    }
+    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;
+    }
+
+    let result = $jp.storageClass === StorageClass.STATIC && $jp.getAncestor("function") === undefined;
+    if ($jp instanceof FunctionJp) {
+        result = result && $jp.isImplementation;
+    }
+    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)
+    });
+}
+
+/**
+ * @returns Returns true if the identifiers represent different AST nodes but are not distinct within the first 31 characters. Otherwise returns false.
+ */
+export function areDistinctIdentifiers($jp1: Vardecl | FunctionJp, $jp2: Vardecl | FunctionJp): boolean {
+    try {
+        return $jp1.astId !== $jp2.ast && $jp1.name.substring(0, 31) !== $jp2.name.substring(0, 31);
+    } catch (error) {
+        return false;
+    }
+}

package/src/utils/JoinpointUtils.ts

@@ -0,0 +1,70 @@
+import { Joinpoint, Type, PointerType, ArrayType, RecordJp, EnumDecl, DeclStmt, Program, QualType, Include } from "@specs-feup/clava/api/Joinpoints.js";
+
+export type TagDecl = RecordJp | EnumDecl;
+
+export function isTagDecl($jp: Joinpoint):  $jp is TagDecl {
+    return $jp instanceof RecordJp || $jp instanceof EnumDecl;
+}
+
+/**
+ * Checks if the provided node has a defined type
+ * @param $jp The joinpoint to check its type
+ * @returns true if the joinpoint has a defined type, otherwise false
+ */
+export function hasDefinedType($jp: Joinpoint): boolean {
+    return $jp.hasType && $jp.type !== null && $jp.type !== undefined;
+}
+
+/**
+ * Retrieves the base type of the provided joinpoint. 
+ * @param $jp The joinpoint to retrieve its type
+ * @returns The base type of the joinpoint, or undefined if the joinpoint does not have a type
+ */
+export function getBaseType($jp: Joinpoint): Type | undefined {
+    if (!hasDefinedType($jp)) return undefined;
+    let jpType = $jp.type instanceof QualType ? $jp.type.unqualifiedType : $jp.type;
+
+    while (jpType instanceof PointerType || jpType instanceof ArrayType) {
+        jpType = jpType instanceof PointerType ? jpType.pointee : jpType.elementType;
+    } 
+    return jpType;
+}
+
+/**
+ * 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}`;
+    }
+    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);
+    
+    if (filepath1 !== filepath2) return getFileLocation($jp1).localeCompare(getFileLocation($jp2));
+
+    if (($jp1 instanceof Include) && !($jp2 instanceof Include)) return -1;
+    if (!($jp1 instanceof Include) && ($jp2 instanceof Include)) return 1;
+
+    return $jp1.line !== $jp2.line ? $jp1.line - $jp2.line : $jp1.column - $jp2.column;
+}