commentGenerator.ts

Go to the documentation of this file.

 
import * as vscode from 'vscode';
import { minimatch } from 'minimatch';
import { CodeConfig, CodeConfigType } from './processConfiguration';
import { query } from './querier';
import { logger } from './logger';
import { getMessage } from './messageProvider';
import { LazyFileLoader } from './lazyFileLoad';
import { RandomLogo, logo } from './randomLogo';
 
interface CommentStyle {
    singleLine: string[];
    multiLine: string[];
    prompt_comment_opening_type: boolean;
    language?: string;
}
 
export class CommentGenerator {
    private Config: CodeConfigType = CodeConfig;
    private randomLogo: RandomLogo = new RandomLogo();
    private languageComment: LazyFileLoader | undefined = undefined;
    private documentBody: vscode.TextDocument | undefined = undefined;
    private filePath: string | undefined = undefined;
    private fileName: string | undefined = undefined;
    private fileExtension: string | undefined = undefined;
    private languageId: string | undefined = undefined;
    private documentEOL: vscode.EndOfLine | undefined = undefined;
    private documentVersion: number | undefined = undefined;
    private headerInnerStart: number | undefined = undefined;
    private headerInnerEnd: number | undefined = undefined;
    private maxScanLength: number = this.Config.get("maxScanLength");
    private headerLogo: string[] = this.Config.get("headerLogo");
    private headerLogoVersions: Record<string, string[]> = this.Config.get("headerLogoVersions");
    private useHeaderLogoVersion: boolean = this.Config.get("useHeaderLogoVersion");
    private headerLogoVersionReference: string = this.Config.get("headerLogoVersionReference");
    private projectName: string = this.Config.get("extensionName");
    private projectCopyRight: string = this.Config.get("projectCopyright");
    private addBlankLineAfterMultiline: boolean = this.Config.get("headerAddBlankLineAfterMultiline");
    private languagePrepend: Record<string, string> = this.Config.get("languagePrepend");
    private languageAppend: Record<string, string> = this.Config.get("languageAppend");
    private singleLineOverride: Record<string, string> = this.Config.get("languageSingleLineComment");
    private multiLineOverride: Record<string, string[]> = this.Config.get("languageMultiLineComment");
    private trimTrailingSpaces: boolean = this.Config.get("removeTrailingHeaderSpaces");
    private preferSingleLineComments: boolean = this.Config.get("preferSingleLineComments");
 
    constructor(languageComment: LazyFileLoader | undefined = undefined, editor: vscode.TextEditor | undefined = undefined, randomLogoInstance: RandomLogo | undefined = undefined) {
        logger.debug(getMessage("inFunction", "constructor", "CommentGenerator"));
        if (languageComment !== undefined) {
            this.languageComment = languageComment;
            logger.debug(getMessage("foundLanguageComment"));
        } else {
            logger.warning(getMessage("missingLanguageComment"));
        }
        if (!editor) {
            logger.warning(getMessage("noFocusedEditors"));
        } else {
            this.updateFileInfo(editor.document);
            logger.debug(getMessage("foundFocusEditor"));
        }
        if (!randomLogoInstance) {
            logger.warning(getMessage("noLogoInstanceProvided"));
        } else {
            this.randomLogo = randomLogoInstance;
            logger.debug(getMessage("foundLogoInstance"));
        }
    }
 
    private determineNewLine(eol: vscode.EndOfLine): string {
        logger.debug(getMessage("inFunction", "determineNewLine", "CommentGenerator"));
        if (eol === vscode.EndOfLine.LF) {
            logger.debug(getMessage("foundNewLine", "\\n"));
            return "\n";
        } else {
            logger.debug(getMessage("foundNewLine", "\\r\\n"));
            return "\r\n";
        }
    }
 
    private headerOpener(comment: string, eol: vscode.EndOfLine, projectName: string = this.Config.get("extensionName")): string {
        logger.debug(getMessage("inFunction", "headerOpener", "CommentGenerator"));
        let final: string = comment + this.Config.get("headerOpenerDecorationOpen");
        final += this.Config.get("telegraphBegin") + " ";
        final += projectName;
        final += this.Config.get("headerOpenerDecorationClose");
        final += this.determineNewLine(eol);
        return final;
    }
 
    private async determineCorrectComment(): Promise<CommentStyle> {
        logger.debug(getMessage("inFunction", "determineCorrectComment", "CommentGenerator"));
        const primaryKey: string = "langs";
        let commentStructure: CommentStyle = {
            singleLine: [],
            multiLine: [],
            prompt_comment_opening_type: false,
            language: undefined,
        };
        if (this.languageComment === undefined) {
            logger.Gui.error(getMessage("missingFileError"));
            return commentStructure;
        }
        const jsonContent = await this.languageComment?.get();
        // logger.info(getMessage("jsonContent", JSON.stringify(jsonContent)));
        if (!jsonContent || typeof jsonContent !== 'object' || jsonContent === null || (primaryKey in jsonContent) === false) {
            logger.Gui.error(getMessage("unknownFileStructure"));
            return commentStructure;
        }
        if (Array.isArray(jsonContent[primaryKey]) === false) {
            logger.Gui.error(getMessage("unknownFileStructure"));
            return commentStructure;
        }
        let index = 0;
        const languageNodes = jsonContent[primaryKey];
        let locatedName: string = "";
        for (; index < languageNodes.length; index++) {
            let nodeFound = false;
            const node = languageNodes[index];
 
            const nodeLangs: string[] = node.langs ?? [];
            const nodeFileExtensions: Record<string, string[]> = node.fileExtensions ?? {};
 
            for (let langIndex = 0; langIndex < nodeLangs.length; langIndex++) {
                const langName = nodeLangs[langIndex].toLowerCase();
                locatedName = langName;
 
                if (langName === this.languageId?.toLowerCase()) {
                    nodeFound = true;
                    break;
                }
 
                if (this.fileExtension) {
                    const extensionsForLang = nodeFileExtensions[langName] ?? [];
                    for (let extIndex = 0; extIndex < extensionsForLang.length; extIndex++) {
                        let dot: string = "";
                        if (extensionsForLang[extIndex].length > 0 && extensionsForLang[extIndex][0] === ".") {
                            dot = ".";
                        }
                        if (extensionsForLang[extIndex] === `${dot}${this.fileExtension}`) {
                            nodeFound = true;
                            break;
                        }
                    }
                }
 
                if (nodeFound) {
                    break;
                }
            }
 
            logger.debug(getMessage("arrayNodeContent", `Json[${primaryKey}]`, index, node));
            if (nodeFound) {
                logger.Gui.info(getMessage("identifiedLanguage", locatedName));
                logger.info(getMessage("arrayNodeContent", `Json[${primaryKey}]`, index, node));
                commentStructure.singleLine = node.singleLine ?? [];
                commentStructure.multiLine = node.multiLine ?? [];
                commentStructure.prompt_comment_opening_type = node.prompt_comment_opening_type ?? false;
                commentStructure.language = locatedName ?? undefined;
                return commentStructure;
            }
        }
        logger.error(getMessage("languageNotFound", String(this.languageId), this.fileExtension));
        return commentStructure;
    }
 
    private async determineHeaderDescription(): Promise<string[]> {
        logger.debug(getMessage("inFunction", "determineHeaderDescription", "CommentGenerator"));
        const rawAny = this.Config.get("projectDescription");
        let intermediate: string = "";
        if (Array.isArray(rawAny)) {
            intermediate = rawAny.join(this.determineNewLine(this.documentEOL || vscode.EndOfLine.LF));
        } else {
            intermediate = String(rawAny ?? "");
        }
        if (intermediate.trim().length === 0) {
            const usrResponse: string | undefined = await query.input(getMessage("getHeaderDescription"));
            intermediate = (usrResponse || "");
        } else {
            logger.debug(getMessage("configDescriptionUsed"));
        }
        const final = intermediate.split(/\r?\n/);
        return final;
    }
 
    private async determineHeaderTags(): Promise<string[]> {
        logger.debug(getMessage("inFunction", "determineHeaderTags", "CommentGenerator"));
        let final: string[] = [];
        const usrResponse: string | undefined = await query.input(getMessage("getHeaderTags"));
        final.push(usrResponse || "");
        return final;
    }
 
    private async determineHeaderPurpose(): Promise<string[]> {
        logger.debug(getMessage("inFunction", "determineHeaderPurpose", "CommentGenerator"));
        let final: string[] = [];
        const usrResponse: string | undefined = await query.input(getMessage("getHeaderPurpose"));
        final.push(usrResponse || "");
        return final;
    }
 
    private async getSingleCommentOption(commentOptions: string[]): Promise<string> {
        logger.debug(getMessage("inFunction", "getSingleCommentOption", "CommentGenerator"));
        if (commentOptions.length === 0) {
            logger.Gui.error(getMessage("noCommentToShow"));
            throw Error(getMessage("noCommentToShow"));
        }
        if (commentOptions.length === 1) {
            logger.info(getMessage("noProvidedCommentOptions"));
            return commentOptions[0];
        }
        const response: string | undefined = await query.quickPick(commentOptions, getMessage("chooseSingleLineCommentOption"));
        return response || commentOptions[0];
    }
 
    private addKeyDefinitionSeparator(): string {
        logger.debug(getMessage("inFunction", "addKeyDefinitionSeparator", "CommentGenerator"));
        const userSettingDefinedElement: string = this.Config.get("headerKeyDefinitionSeparator");
        return userSettingDefinedElement || this.Config.get("headerKeyDefinitionSeparator");
    }
 
    private addCreationDate(comment: string, eol: vscode.EndOfLine) {
        logger.debug(getMessage("inFunction", "addCreationDate", "CommentGenerator"));
        const now = new Date();
        const day = String(now.getDate()).padStart(2, "0");
        const month = String(now.getMonth() + 1).padStart(2, "0"); // Months are 0-based
        const year = now.getFullYear();
        const separatorDay: string = this.Config.get("headerDateSeperatorDay");
        const separatorMonth: string = this.Config.get("headerDateSeperatorMonth");
        const separatorYear: string = this.Config.get("headerDateSeperatorYear");
        let final: string = comment + this.Config.get("headerCreationDateKey") + this.addKeyDefinitionSeparator();
        final += `${day}${separatorDay}${month}${separatorMonth}${year}${separatorYear}`;
        final += this.determineNewLine(eol);
        return final;
    }
 
    private addLastModifiedDate(comment: string, eol: vscode.EndOfLine) {
        logger.debug(getMessage("inFunction", "addLastModifiedDate", "CommentGenerator"));
        const now: Date = new Date();
        const day: string = String(now.getDate()).padStart(2, "0");
        const month: string = String(now.getMonth() + 1).padStart(2, "0"); // Months are 0-based
        const year: number = now.getFullYear();
        const hour: number = now.getHours();
        const minute: number = now.getMinutes();
        const seconds: number = now.getSeconds();
        const separatorDay: string = this.Config.get("headerDateSeperatorDay");
        const separatorMonth: string = this.Config.get("headerDateSeperatorMonth");
        const separatorYear: string = this.Config.get("headerDateSeperatorYear");
        const separatorTimeAndDate: string = this.Config.get("headerTimeAndDateSeperator");
        const separatorSecond: string = this.Config.get("headerTimeSeperatorSecond");
        const separatorMinute: string = this.Config.get("headerTimeSeperatorMinute");
        const separatorHour: string = this.Config.get("headerTimeSeperatorHour");
        let final: string = comment + this.Config.get("headerLastModifiedKey") + this.addKeyDefinitionSeparator();
        final += `${hour}${separatorHour}${minute}${separatorMinute}${seconds}${separatorSecond}${separatorTimeAndDate}${day}${separatorDay}${month}${separatorMonth}${year}${separatorYear}`;
        final += this.determineNewLine(eol);
        return final;
    }
 
    private mySmartTrimmer(content: string): string {
        if (this.trimTrailingSpaces) {
            return content.trimEnd();
        }
        return content;
    }
 
    private addMultilineKey(comment: string, eol: vscode.EndOfLine, tagName: string, tagDefinition: string[]): string {
        logger.debug(getMessage("inFunction", "addMultilineKey", "CommentGenerator"));
        const eolStr: string = this.determineNewLine(eol);
        const keyLine: string = comment + tagName + this.mySmartTrimmer(this.addKeyDefinitionSeparator()) + eolStr;
        let final: string = keyLine;
        for (let i = 0; i < tagDefinition.length; i++) {
            final += comment + tagDefinition[i] + eolStr;
        }
        final += comment + this.Config.get("telegraphBlockStop") + eolStr;
        if (this.addBlankLineAfterMultiline) {
            final += comment + eolStr;
        }
        return final;
    }
 
    private addSingleLineKey(comment: string, eol: vscode.EndOfLine, tagName: string, tagDefinition: string): string {
        logger.debug(getMessage("inFunction", "addSingleLineKey", "CommentGenerator"));
        let final: string = comment + tagName + this.addKeyDefinitionSeparator();
        final += tagDefinition + this.determineNewLine(eol);
        return final;
    }
 
    private beforeHeaderCloser(comment: string, eol: vscode.EndOfLine): string {
        logger.debug(getMessage("inFunction", "beforeHeaderCloser", "CommentGenerator"));
        return comment + this.Config.get("telegraphEndOfTransmission") + this.determineNewLine(eol);
    }
 
    private headerCloser(comment: string, eol: vscode.EndOfLine, projectName: string = this.Config.get("extensionName")): string {
        logger.debug(getMessage("inFunction", "headerCloser", "CommentGenerator"));
        let final: string = comment + this.Config.get("headerOpenerDecorationOpen");
        final += this.Config.get("telegraphEnd") + " ";
        final += projectName;
        final += this.Config.get("headerOpenerDecorationClose");
        final += this.determineNewLine(eol);
        return final;
    }
 
    private updateFileInfo(document: vscode.TextDocument) {
        logger.debug(getMessage("inFunction", "updateFileInfo", "CommentGenerator"));
        this.headerInnerEnd = undefined;
        this.headerInnerStart = undefined;
        this.documentBody = document;
        // Refresh all configuration-derived caches dynamically so user settings changes apply without reload (1.0.22)
        this.headerLogo = this.Config.get("headerLogo");
        this.headerLogoVersions = this.Config.get("headerLogoVersions");
        this.useHeaderLogoVersion = this.Config.get("useHeaderLogoVersion");
        this.headerLogoVersionReference = this.Config.get("headerLogoVersionReference");
        this.languagePrepend = this.Config.get("languagePrepend");
        this.languageAppend = this.Config.get("languageAppend");
        this.singleLineOverride = this.Config.get("languageSingleLineComment");
        this.multiLineOverride = this.Config.get("languageMultiLineComment");
        this.trimTrailingSpaces = this.Config.get("removeTrailingHeaderSpaces");
        this.preferSingleLineComments = this.Config.get("preferSingleLineComments");
        if (this.Config.get("useWorkspaceNameWhenAvailable")) {
            this.projectName = this.Config.get("workspaceName") || this.Config.get("extensionName");
        } else {
            this.projectName = this.Config.get("extensionName");
        }
        this.filePath = this.documentBody.uri.fsPath;
        this.projectCopyRight = this.Config.get("projectCopyright");
        this.addBlankLineAfterMultiline = this.Config.get("headerAddBlankLineAfterMultiline");
        // Dynamic scan budget: base maxScanLength (user-configurable, fallback to defaultMaxScanLength via processConfiguration) + current logo height
        const baseScanLength: number = this.Config.get("maxScanLength");
        this.maxScanLength = baseScanLength;
        if (this.useHeaderLogoVersion) {
            if (this.headerLogoVersionReference in this.headerLogoVersions) {
                logger.debug(getMessage("headerLogoReference", this.headerLogoVersionReference));
                this.maxScanLength += this.headerLogoVersions[this.headerLogoVersionReference].length;
            } else {
                logger.error(getMessage("headerLogoReferenceNotFound", this.headerLogoVersionReference));
            }
        } else {
            logger.debug(getMessage("headerLogoVersionDisabled"));
            this.maxScanLength += this.headerLogo.length;
        }
        this.fileName = this.documentBody.uri.path.split('/').pop() || "unknown";
        if (this.fileName.includes('.')) {
            this.fileExtension = this.fileName.split('.').pop() || "none";
        } else {
            this.fileExtension = "none";
        };
        this.languageId = this.documentBody.languageId;
        this.documentEOL = this.documentBody.eol;
        this.documentVersion = this.documentBody.version;
    }
 
    private prependIfPresent(buildHeader: string[], eol: vscode.EndOfLine, languageId?: string): string[] {
        if (languageId === undefined) {
            return buildHeader;
        }
        const instance = this.languagePrepend[languageId];
        if (instance !== undefined) {
            let instanceCleaned: string = instance;
            if (Array.isArray(instance)) {
                instanceCleaned = instance.join(this.determineNewLine(eol));
            }
            buildHeader.push(instanceCleaned);
            logger.debug(getMessage("languagePrependApplied", languageId, instanceCleaned));
        }
        return buildHeader;
    }
 
    private appendIfPresent(buildHeader: string[], eol: vscode.EndOfLine, languageId?: string): string[] {
        if (languageId === undefined) {
            return buildHeader;
        }
        const instance = this.languageAppend[languageId];
        if (instance !== undefined) {
            let instanceCleaned: string = instance;
            if (Array.isArray(instance)) {
                instanceCleaned = instance.join(this.determineNewLine(eol));
            }
            buildHeader.push(instanceCleaned);
            logger.debug(getMessage("languageAppendApplied", languageId, instanceCleaned));
        }
        return buildHeader;
    }
 
    private getOverrideIfPresent(determinedComment: CommentStyle): CommentStyle {
        // If the language is not known, nothing to override
        if (!determinedComment.language) {
            return determinedComment;
        }
 
        const languageId = determinedComment.language;
 
        // Apply single-line override if present
        const singleOverride = this.singleLineOverride[languageId];
        if (singleOverride !== undefined) {
            // Wrap the single string into an array since CommentStyle.singleLine expects string[]
            if (Array.isArray(singleOverride)) {
                determinedComment.singleLine = singleOverride;
            } else {
                determinedComment.singleLine = [singleOverride];
            }
            logger.debug(getMessage("singleLineCommentOverrideApplied", languageId, determinedComment.singleLine));
        }
 
        // Apply multi-line override if present
        const multiOverride = this.multiLineOverride[languageId];
        if (multiOverride !== undefined) {
            // multiOverride is already a string[]
            determinedComment.multiLine = multiOverride;
            logger.debug(getMessage("multiLineCommentOverrideApplied", languageId, determinedComment.multiLine));
        }
 
        return determinedComment;
    }
    private async getCorrectCommentPrefix(determinedComment: CommentStyle): Promise<string[]> {
        logger.debug(getMessage("inFunction", "getCorrectPrefix", "CommentGenerator"));
        let commentOpener: string = "";
        let commentMiddle: string = "";
        let commentCloser: string = "";
        const determinedComment_checked: CommentStyle = this.getOverrideIfPresent(determinedComment);
        if (determinedComment_checked.multiLine.length >= 2 && this.preferSingleLineComments === false) {
            commentOpener = determinedComment_checked.multiLine[0];
            if (determinedComment_checked.multiLine.length >= 3) {
                commentMiddle = determinedComment_checked.multiLine[1];
                commentCloser = determinedComment_checked.multiLine[2];
            } else {
                commentMiddle = "";
                commentCloser = determinedComment_checked.multiLine[1];
            }
        } else if (determinedComment_checked.singleLine.length > 0) {
            if (determinedComment_checked.prompt_comment_opening_type) {
                // Ask the user for the type to use based on the single comments that are present.
                const commentString: string = await this.getSingleCommentOption(determinedComment_checked.singleLine);
                commentOpener = commentString;
                commentMiddle = commentString;
                commentCloser = commentString;
            } else {
                commentOpener = determinedComment_checked.singleLine[0];
                commentMiddle = determinedComment_checked.singleLine[0];
                commentCloser = determinedComment_checked.singleLine[0];
            }
        } else {
            commentOpener = "";
            commentMiddle = "";
            commentCloser = "";
        }
        commentOpener += this.Config.get("headerCommentSpacing");
        commentMiddle += this.Config.get("headerCommentSpacing");
        commentCloser += this.Config.get("headerCommentSpacing");
 
        return [commentOpener, commentMiddle, commentCloser];
    }
 
    private async buildTheHeader(comments: string[], languageId?: string): Promise<string[]> {
        logger.debug(getMessage("inFunction", "buildTheHeader", "CommentGenerator"));
        const eol: vscode.EndOfLine = this.documentEOL || vscode.EndOfLine.LF;
        const unknownTerm: string = getMessage("unknown");
        const commentOpener: string = comments[0] || "";
        const commentMiddle: string = comments[1] || "";
        const commentCloser: string = comments[2] || "";
        let buildHeader: string[] = [];
        // Check wether there are elements required to be added before the header
        buildHeader = this.prependIfPresent(buildHeader, eol, languageId);
        // Preparing the header content so that it can be put in a comment and written.
        if (commentOpener.length > 0) {
            buildHeader.push(`${this.mySmartTrimmer(commentOpener)}${this.determineNewLine(eol)}`);
        }
        // Opening the header
        buildHeader.push(this.headerOpener(commentMiddle, eol, this.projectName));
        // The logo - fully dynamic (1.0.22): read fresh config so settings changes apply without reload
        const freshLogo: string[] = this.Config.get("headerLogo");
        const freshVersions: Record<string, string[]> = this.Config.get("headerLogoVersions");
        const freshUseVersion: boolean = this.Config.get("useHeaderLogoVersion");
        const freshRef: string = this.Config.get("headerLogoVersionReference");
        // Keep caches in sync for callers that read them directly
        this.headerLogo = freshLogo;
        this.headerLogoVersions = freshVersions;
        this.useHeaderLogoVersion = freshUseVersion;
        this.headerLogoVersionReference = freshRef;
        let logoContent = freshLogo;
        if (this.Config.get("randomLogo") === true) {
            try {
                const gatheredLogo: logo = await this.randomLogo.getRandomLogoFromFolder();
                if (gatheredLogo.logoContent !== undefined) {
                    logoContent = gatheredLogo.logoContent;
                } else {
                    logger.error(getMessage("randomLogoGatheringFailed", getMessage("ramdomLogoGatheringLogoUndefined")));
                }
            } catch (e) {
                logger.error(getMessage("randomLogoGatheringFailed", String(e)));
            }
        } else if (freshUseVersion === true) {
            if (freshRef in freshVersions) {
                logger.debug(getMessage("headerLogoReference", freshRef));
                logoContent = freshVersions[freshRef];
            } else {
                logger.error(getMessage("headerLogoReferenceNotFound", freshRef));
                logger.Gui.error(getMessage("headerLogoReferenceNotFoundGUI", freshRef));
            }
        }
        buildHeader.push(this.addMultilineKey(commentMiddle, eol, this.Config.get("headerLogoKey"), logoContent));
        // The project name
        buildHeader.push(this.addSingleLineKey(commentMiddle, eol, this.Config.get("headerProjectKey"), this.projectName));
        // The file name
        buildHeader.push(this.addSingleLineKey(commentMiddle, eol, this.Config.get("headerFileKey"), this.fileName || unknownTerm));
        // The Creation date
        buildHeader.push(this.addCreationDate(commentMiddle, eol));
        // The Last modified date
        buildHeader.push(this.addLastModifiedDate(commentMiddle, eol));
        // The description
        buildHeader.push(this.addMultilineKey(commentMiddle, eol, this.Config.get("headerDescriptionKey"), await this.determineHeaderDescription()));
        // The copyright
        buildHeader.push(this.addSingleLineKey(commentMiddle, eol, this.Config.get("headerCopyrightKey"), this.projectCopyRight));
        // The Tag
        // buildHeader.push(this.addSingleLineKey(commentMiddle, eol, this.Config.get("headerTagKey"), (await this.determineHeaderTags()).join(",")));
        // The Purpose
        buildHeader.push(this.addSingleLineKey(commentMiddle, eol, this.Config.get("headerPurposeKey"), (await this.determineHeaderPurpose()).join(";")));
        // End of transmission telegraph
        buildHeader.push(this.beforeHeaderCloser(commentMiddle, eol));
        // Closing the header 
        buildHeader.push(this.headerCloser(commentMiddle, eol, this.projectName));
        if (commentCloser.length > 0) {
            buildHeader.push(`${commentCloser}${this.determineNewLine(eol)}`);
        }
        // Check wether there are elements required to be added after the header
        buildHeader = this.appendIfPresent(buildHeader, eol, languageId);
        return buildHeader;
    }
 
    private async updateEditDate(document: vscode.TextDocument, comments: string[]) {
        logger.debug(getMessage("inFunction", "updateEditDate", "CommentGenerator"));
        const commentOpener: string = comments[0] || "";
        const commentMiddle: string = comments[1] || "";
        const commentCloser: string = comments[2] || "";
        if (this.headerInnerStart === undefined || this.headerInnerEnd === undefined) {
            const errMsg: string = getMessage("updateEditDateMissingBounds");
            logger.error(errMsg);
            logger.Gui.error(errMsg);
            return;
        }
        if (!this.documentBody) {
            const errMsg: string = getMessage("emptyDocument");
            logger.error(errMsg);
            logger.Gui.error(errMsg);
            return;
        }
 
        const eol = this.documentEOL || vscode.EndOfLine.LF;
        const lastModifiedKey = this.Config.get("headerLastModifiedKey");
 
        // Build the new "Last Modified" line
        const newLine = this.addLastModifiedDate(commentMiddle, eol).trimEnd();
 
        let targetLine: number | undefined = undefined;
 
        // Scan header block to locate the "Last Modified" line
        for (let i = this.headerInnerStart; i <= this.headerInnerEnd; i++) {
            const lineText = this.documentBody.lineAt(i).text;
            if (lineText.includes(lastModifiedKey)) {
                targetLine = i;
                break;
            }
        }
 
        if (targetLine === undefined) {
            const errMsg: string = getMessage("lastModifiedLineNotFound");
            logger.error(errMsg);
            logger.Gui.error(errMsg);
            return;
        }
 
        const edit = new vscode.WorkspaceEdit();
        const range = document.lineAt(targetLine).range;
        edit.replace(document.uri, range, newLine);
        await vscode.workspace.applyEdit(edit);
 
        const msg: string = getMessage("lastModifiedUpdated");
        logger.info(msg);
        logger.Gui.info(msg);
    }
 
    protected locateIfHeaderPresent(comments: string[]): boolean | undefined {
        logger.debug(getMessage("inFunction", "locateIfHeaderPresent", "CommentGenerator"));
        const commentOpener: string = comments[0] || "";
        const commentMiddle: string = comments[1] || "";
        const commentCloser: string = comments[2] || "";
        this.headerInnerStart = undefined;
        this.headerInnerEnd = undefined;
        if (this.documentBody === undefined) {
            logger.error(getMessage("emptyDocument"));
            return undefined;
        }
        if (this.documentBody.isClosed) {
            logger.warning(getMessage("closedDocument"));
            return undefined;
        }
        const documentTotalLines: number = this.documentBody.lineCount;
        const eol: vscode.EndOfLine = this.documentEOL ?? vscode.EndOfLine.LF;
        const opener: string = this.headerOpener(commentMiddle, eol, this.projectName).trimEnd();
        const closer: string = this.headerCloser(commentMiddle, eol, this.projectName).trimEnd();
        const scanLines: number = Math.min(this.maxScanLength, documentTotalLines);
        const graceLines: number = Math.min((this.maxScanLength * 2), documentTotalLines);
        let lineOpenerFound: boolean = false;
        let lineCloserFound: boolean = false;
        for (let i = 0; i < scanLines || (i < graceLines && lineOpenerFound && !lineCloserFound); i++) {
            const lineText = this.documentBody.lineAt(i).text;
            if (i >= scanLines) {
                logger.info(getMessage("graceLines"));
            }
 
            // If we encounter a closer before any opener, the header is broken
            if (lineText === closer && !lineOpenerFound) {
                logger.Gui.warning(getMessage("brokenHeader"));
                return false;
            }
 
            // If we encounter an opener after a closer was already found, header is broken
            if (lineText === opener && lineCloserFound) {
                logger.Gui.warning(getMessage("brokenHeader"));
                return false;
            }
 
            // Detect opener
            if (lineText === opener && !lineOpenerFound) {
                lineOpenerFound = true;
                this.headerInnerStart = i;
                logger.info(getMessage("headerOpenerFound"));
                continue;
            }
 
            // Detect closer (only valid if opener was already seen)
            if (lineText === closer && !lineCloserFound) {
                this.headerInnerEnd = i;
                lineCloserFound = true;
            }
 
            if (lineCloserFound && lineOpenerFound) {
                logger.info(getMessage("headerOpenerAndCloserFound"));
                return true;
            }
        }
        logger.Gui.warning(getMessage("documentLineScanExceeded", this.maxScanLength));
        return false;
    }
 
    private skipFirstLineInDocument(document: vscode.TextDocument): number {
        let insertLine = 0;
 
        if (document.lineCount > 0) {
            const firstLine = document.lineAt(0).text;
            if (firstLine.startsWith("#!")) {
                insertLine = 1;
            }
        }
        return insertLine;
    }
 
    private async writeHeaderToFile(document: vscode.TextDocument, comments: string[], languageId?: string): Promise<number> {
        logger.debug(getMessage("inFunction", "writeHeaderToFile", "CommentGenerator"));
 
        const headerLines = await this.buildTheHeader(comments, languageId);
        const headerText = headerLines.join("");
        const edit = new vscode.WorkspaceEdit();
        const insertLine: number = this.skipFirstLineInDocument(document);
        edit.insert(
            document.uri,
            new vscode.Position(insertLine, 0),
            headerText
        );
 
        await vscode.workspace.applyEdit(edit);
        return this.Config.get("statusSuccess");
    }
 
    async injectHeader() {
        logger.debug(getMessage("inFunction", "injectHeader", "CommentGenerator"));
        const editor = vscode.window.activeTextEditor;
        if (editor === undefined) {
            logger.error(getMessage("noFocusedEditors"));
            logger.Gui.error(getMessage("openFileToApplyHeader"));
            return;
        }
        this.updateFileInfo(editor.document);
        // Checking that the meta data is filled out.
        if (
            this.documentBody === undefined || this.filePath === undefined
            || this.fileName === undefined || this.fileExtension === undefined
            || this.languageId === undefined || this.documentEOL === undefined
            || this.documentVersion === undefined
        ) {
            logger.error(getMessage("corruptedFileMetaData"));
            logger.Gui.error(getMessage("errorDuringFunctionCall", "injectHeader"));
            return;
        }
        // Making sure that the target document is still open.
        if (this.documentBody.isClosed) {
            logger.warning(getMessage("closedDocument"));
            logger.Gui.warning(getMessage("updateAbortedBecauseFileClosedSyncCancelled"));
            return;
        }
        // Some logging
        const msg = getMessage("inputArgs", JSON.stringify(this.documentBody), JSON.stringify(this.filePath), JSON.stringify(this.fileName), JSON.stringify(this.fileExtension), JSON.stringify(this.languageId), JSON.stringify(this.documentEOL), JSON.stringify(this.documentVersion));
        logger.Gui.debug(msg);
        logger.debug(msg);
        // Determining the correct comment prefix
        const determineComment: CommentStyle = await this.determineCorrectComment();
        const comments: string[] = await this.getCorrectCommentPrefix(determineComment);
        // attempt to locate the header
        let response: boolean | undefined = this.locateIfHeaderPresent(comments);
        if (response === undefined) {
            logger.Gui.warning(getMessage("updateAbortedBecauseFileClosedSyncCancelled"));
            return;
        }
        if (response === true) {
            logger.Gui.info(getMessage("updatingEditionDate"));
            await this.updateEditDate(editor.document, comments);
            return;
        }
        if (response === false) {
            let status: number = await this.writeHeaderToFile(editor.document, comments, determineComment.language);
            if (status === this.Config.get("statusError")) {
                logger.Gui.error(getMessage("headerWriteFailed"));
                return;
            }
            logger.Gui.info(getMessage("headerWriteSuccess"));
        }
    }
 
    private async allowedToActivate(): Promise<boolean> {
        logger.debug(getMessage("inFunction", "allowedToActivate", "CommentGenerator"));
        const ignored: string[] = CodeConfig.get("extensionIgnore") ?? [];
 
        for (const pattern of ignored) {
            if (
                this.fileExtension && minimatch(this.fileExtension, pattern) ||
                this.fileName && minimatch(this.fileName, pattern) ||
                this.filePath && minimatch(this.filePath, pattern)
            ) {
                return false;
            }
        }
 
        return true;
    }
 
    updateLogoInstanceRandomiser(randomLogoInstance: RandomLogo): void {
        logger.debug(getMessage("inFunction", "updateLogoInstanceRandomiser", "CommentGenerator"));
        this.randomLogo = randomLogoInstance;
    }
 
    async refreshHeader(document: vscode.TextDocument | undefined) {
        logger.debug(getMessage("inFunction", "refreshHeader", "CommentGenerator"));
        const refreshOnSave: boolean = CodeConfig.get("refreshOnSave");
        const promptToCreateIfMissing: boolean = CodeConfig.get("promptToCreateIfMissing");
        if (!refreshOnSave) {
            return;
        }
        if (document === undefined) {
            logger.error(getMessage("noDocumentProvided"));
            return;
        }
        this.updateFileInfo(document);
        // Checking that the meta data is filled out.
        if (
            this.documentBody === undefined || this.filePath === undefined
            || this.fileName === undefined || this.fileExtension === undefined
            || this.languageId === undefined || this.documentEOL === undefined
            || this.documentVersion === undefined
        ) {
            logger.error(getMessage("corruptedFileMetaData"));
            logger.Gui.error(getMessage("errorDuringFunctionCall", "injectHeader"));
            return;
        }
        // Check that the file is not in the exclusion list.
        if (!await this.allowedToActivate()) {
            logger.info(getMessage("fileExcludedActivationDisabled"));
            return;
        }
        // Making sure that the target document is still open.
        if (this.documentBody.isClosed) {
            logger.warning(getMessage("closedDocument"));
            logger.Gui.warning(getMessage("updateAbortedBecauseFileClosedSyncCancelled"));
            return;
        }
        // Some logging
        const msg = getMessage("inputArgs", JSON.stringify(this.documentBody), JSON.stringify(this.filePath), JSON.stringify(this.fileName), JSON.stringify(this.fileExtension), JSON.stringify(this.languageId), JSON.stringify(this.documentEOL), JSON.stringify(this.documentVersion));
        logger.Gui.debug(msg);
        logger.debug(msg);
        // Determining the correct comment prefix
        const determineComment: CommentStyle = await this.determineCorrectComment();
        const comments: string[] = await this.getCorrectCommentPrefix(determineComment);
        // attempt to locate the header
        const response: boolean | undefined = this.locateIfHeaderPresent(comments);
        if (response === undefined) {
            logger.Gui.warning(getMessage("updateAbortedBecauseFileClosedSyncCancelled"));
            return;
        }
        if (response === false) {
            if (!promptToCreateIfMissing) {
                logger.Gui.info(getMessage("headerNotFound"));
                return;
            }
            logger.Gui.warning(getMessage("headerNotFound"));
            const questionResponse: boolean = await query.confirm(getMessage("headerInjectQuestion"));
            if (questionResponse === false) {
                logger.Gui.info(getMessage("headerInjectQuestionRefused"));
                return;
            }
            const status: number = await this.writeHeaderToFile(document, comments, determineComment.language);
            if (status === this.Config.get("statusError")) {
                logger.Gui.error(getMessage("headerWriteFailed"));
                return;
            }
            logger.Gui.info(getMessage("headerWriteSuccess"));
        }
        if (response === true) {
            logger.Gui.info(getMessage("updatingEditionDate"));
            await this.updateEditDate(document, comments);
            return;
        }
    }
}