circuitscript 0.3.2 → 0.4.0

package/dist/esm/LexerDiagnosticListener.js

@@ -0,0 +1,371 @@
+import { CircuitScriptParser } from "./antlr/CircuitScriptParser.js";
+export class LexerDiagnosticCollector {
+    startTime = 0n;
+    tokenStartTime = 0n;
+    totalTokens = 0;
+    totalCharactersProcessed = 0;
+    tokenTypeStats = new Map();
+    slowestTokens = [];
+    peakCharacterPosition = 0;
+    indentCount = 0;
+    dedentCount = 0;
+    newlineCount = 0;
+    queueSizeSum = 0;
+    queueSizeCount = 0;
+    maxQueueSize = 0;
+    largeQueueLocations = [];
+    tokenStream = [];
+    verboseLogging = false;
+    recordTokenStream = false;
+    sourceText = '';
+    tokenTypeNameCache = new Map();
+    enabled = true;
+    constructor() {
+        this.reset();
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    setVerboseLogging(enabled) {
+        this.verboseLogging = enabled;
+        if (enabled)
+            this.recordTokenStream = true;
+    }
+    setRecordTokenStream(enabled) {
+        this.recordTokenStream = enabled;
+    }
+    setSourceText(sourceText) {
+        this.sourceText = sourceText;
+    }
+    reset() {
+        this.startTime = process.hrtime.bigint();
+        this.tokenStartTime = 0n;
+        this.totalTokens = 0;
+        this.totalCharactersProcessed = 0;
+        this.tokenTypeStats.clear();
+        this.slowestTokens = [];
+        this.peakCharacterPosition = 0;
+        this.indentCount = 0;
+        this.dedentCount = 0;
+        this.newlineCount = 0;
+        this.queueSizeSum = 0;
+        this.queueSizeCount = 0;
+        this.maxQueueSize = 0;
+        this.largeQueueLocations = [];
+        this.tokenStream = [];
+        this.tokenTypeNameCache.clear();
+    }
+    onTokenStart() {
+        if (!this.enabled)
+            return;
+        this.tokenStartTime = process.hrtime.bigint();
+    }
+    onTokenGenerated(token, queueSize) {
+        if (!this.enabled)
+            return;
+        const endTime = process.hrtime.bigint();
+        const elapsedNs = endTime - this.tokenStartTime;
+        const elapsedUs = Number(elapsedNs) / 1000;
+        this.totalTokens++;
+        if (token.stop > this.peakCharacterPosition) {
+            this.peakCharacterPosition = token.stop;
+        }
+        const tokenLength = token.stop - token.start + 1;
+        this.totalCharactersProcessed += tokenLength;
+        const tokenTypeName = this.getTokenTypeName(token.type);
+        let stats = this.tokenTypeStats.get(tokenTypeName);
+        if (!stats) {
+            stats = {
+                count: 0,
+                totalTimeUs: 0,
+                averageTimeUs: 0,
+                totalCharacters: 0
+            };
+            this.tokenTypeStats.set(tokenTypeName, stats);
+        }
+        stats.count++;
+        stats.totalTimeUs += elapsedUs;
+        stats.averageTimeUs = stats.totalTimeUs / stats.count;
+        stats.totalCharacters += tokenLength;
+        if (token.type === CircuitScriptParser.INDENT) {
+            this.indentCount++;
+        }
+        else if (token.type === CircuitScriptParser.DEDENT) {
+            this.dedentCount++;
+        }
+        else if (token.type === CircuitScriptParser.NEWLINE) {
+            this.newlineCount++;
+        }
+        if (elapsedUs > 10) {
+            this.slowestTokens.push({
+                type: tokenTypeName,
+                timeUs: elapsedUs,
+                text: token.text?.substring(0, 50) || '',
+                line: token.line,
+                column: token.column
+            });
+            this.slowestTokens.sort((a, b) => b.timeUs - a.timeUs);
+            if (this.slowestTokens.length > 20) {
+                this.slowestTokens = this.slowestTokens.slice(0, 20);
+            }
+        }
+        this.queueSizeSum += queueSize;
+        this.queueSizeCount++;
+        if (queueSize > this.maxQueueSize) {
+            this.maxQueueSize = queueSize;
+        }
+        if (queueSize > 50) {
+            this.largeQueueLocations.push({
+                queueSize,
+                tokenIndex: this.totalTokens,
+                line: token.line,
+                column: token.column,
+                tokenType: tokenTypeName,
+                text: token.text?.substring(0, 50) || ''
+            });
+            this.largeQueueLocations.sort((a, b) => b.queueSize - a.queueSize);
+            if (this.largeQueueLocations.length > 50) {
+                this.largeQueueLocations = this.largeQueueLocations.slice(0, 50);
+            }
+        }
+        if (this.recordTokenStream) {
+            const tokenEntry = {
+                index: this.totalTokens - 1,
+                type: tokenTypeName,
+                text: token.text || '',
+                line: token.line,
+                column: token.column,
+                startPos: token.start,
+                stopPos: token.stop,
+                channel: token.channel,
+                timeUs: elapsedUs
+            };
+            this.tokenStream.push(tokenEntry);
+            if (this.verboseLogging) {
+                this.logToken(tokenEntry);
+            }
+        }
+    }
+    getTokenTypeName(tokenType) {
+        let name = this.tokenTypeNameCache.get(tokenType);
+        if (name !== undefined)
+            return name;
+        const symbolicName = CircuitScriptParser.vocabulary.getSymbolicName(tokenType);
+        if (symbolicName) {
+            this.tokenTypeNameCache.set(tokenType, symbolicName);
+            return symbolicName;
+        }
+        const literalName = CircuitScriptParser.vocabulary.getLiteralName(tokenType);
+        if (literalName) {
+            this.tokenTypeNameCache.set(tokenType, literalName);
+            return literalName;
+        }
+        name = `TOKEN_TYPE_${tokenType}`;
+        this.tokenTypeNameCache.set(tokenType, name);
+        return name;
+    }
+    logToken(token) {
+        const textPreview = token.text.length > 40
+            ? token.text.substring(0, 37) + '...'
+            : token.text;
+        const displayText = textPreview.replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t');
+        console.log(`[${token.index.toString().padStart(5)}] ` +
+            `${token.type.padEnd(18)} ` +
+            `@${token.line}:${token.column.toString().padStart(3)} ` +
+            `[${token.startPos}-${token.stopPos}] ` +
+            `"${displayText}"`);
+    }
+    getDiagnostics() {
+        const endTime = process.hrtime.bigint();
+        const totalTimeNs = endTime - this.startTime;
+        const totalTimeUs = Number(totalTimeNs) / 1000;
+        const averageQueueSize = this.queueSizeCount > 0
+            ? this.queueSizeSum / this.queueSizeCount
+            : 0;
+        return {
+            totalTokens: this.totalTokens,
+            totalCharactersProcessed: this.totalCharactersProcessed,
+            totalTimeMicroseconds: totalTimeUs,
+            tokenTypeStats: this.tokenTypeStats,
+            averageTokenTimeUs: this.totalTokens > 0 ? totalTimeUs / this.totalTokens : 0,
+            slowestTokens: this.slowestTokens,
+            peakCharacterPosition: this.peakCharacterPosition,
+            indentCount: this.indentCount,
+            dedentCount: this.dedentCount,
+            newlineCount: this.newlineCount,
+            maxQueueSize: this.maxQueueSize,
+            averageQueueSize: averageQueueSize,
+            largeQueueLocations: this.largeQueueLocations,
+            tokenStream: this.tokenStream
+        };
+    }
+    printReport() {
+        const diagnostics = this.getDiagnostics();
+        console.log('\n=== Lexer Diagnostic Report ===\n');
+        console.log('Overall Statistics:');
+        console.log(`  Total tokens generated: ${diagnostics.totalTokens}`);
+        console.log(`  Total characters processed: ${diagnostics.totalCharactersProcessed}`);
+        console.log(`  Total time: ${(diagnostics.totalTimeMicroseconds / 1000).toFixed(2)} ms`);
+        console.log(`  Average time per token: ${diagnostics.averageTokenTimeUs.toFixed(2)} μs`);
+        console.log(`  Tokens per second: ${(diagnostics.totalTokens / (diagnostics.totalTimeMicroseconds / 1000000)).toFixed(0)}`);
+        console.log('\nIndentation Statistics:');
+        console.log(`  INDENT tokens: ${diagnostics.indentCount}`);
+        console.log(`  DEDENT tokens: ${diagnostics.dedentCount}`);
+        console.log(`  NEWLINE tokens: ${diagnostics.newlineCount}`);
+        console.log('\nToken Queue Statistics:');
+        console.log(`  Max queue size: ${diagnostics.maxQueueSize}`);
+        console.log(`  Average queue size: ${diagnostics.averageQueueSize.toFixed(2)}`);
+        console.log('\nTop Token Types by Count:');
+        const sortedByCount = Array.from(diagnostics.tokenTypeStats.entries())
+            .sort((a, b) => b[1].count - a[1].count)
+            .slice(0, 10);
+        sortedByCount.forEach(([type, stats]) => {
+            const percentage = (stats.count / diagnostics.totalTokens * 100).toFixed(1);
+            console.log(`  ${type.padEnd(20)} ${stats.count.toString().padStart(6)} (${percentage}%)  avg: ${stats.averageTimeUs.toFixed(2)} μs`);
+        });
+        console.log('\nTop Token Types by Time:');
+        const sortedByTime = Array.from(diagnostics.tokenTypeStats.entries())
+            .sort((a, b) => b[1].totalTimeUs - a[1].totalTimeUs)
+            .slice(0, 10);
+        sortedByTime.forEach(([type, stats]) => {
+            const percentage = (stats.totalTimeUs / diagnostics.totalTimeMicroseconds * 100).toFixed(1);
+            console.log(`  ${type.padEnd(20)} ${(stats.totalTimeUs / 1000).toFixed(2).padStart(8)} ms (${percentage}%)  count: ${stats.count}`);
+        });
+        if (diagnostics.slowestTokens.length > 0) {
+            console.log('\nSlowest Individual Tokens:');
+            diagnostics.slowestTokens.slice(0, 10).forEach((token, idx) => {
+                const textPreview = token.text.length > 30
+                    ? token.text.substring(0, 27) + '...'
+                    : token.text;
+                console.log(`  ${(idx + 1).toString().padStart(2)}. ${token.type.padEnd(15)} ${token.timeUs.toFixed(2).padStart(8)} μs  at ${token.line}:${token.column}  "${textPreview}"`);
+            });
+        }
+        if (diagnostics.largeQueueLocations.length > 0) {
+            const earlyThreshold = Math.min(100, diagnostics.totalTokens * 0.05);
+            const earlyQueues = diagnostics.largeQueueLocations.filter(loc => loc.tokenIndex <= earlyThreshold);
+            const laterQueues = diagnostics.largeQueueLocations.filter(loc => loc.tokenIndex > earlyThreshold);
+            if (earlyQueues.length > 0) {
+                console.log('\nLarge Token Queue Locations (Early - Expected from script rule):');
+                console.log(`  Max queue: ${earlyQueues[0]?.queueSize || 0} at token ${earlyQueues[0]?.tokenIndex || 0}`);
+            }
+            if (laterQueues.length > 0) {
+                console.log('\nLarge Token Queue Locations (Later - Potentially Problematic):');
+                laterQueues.slice(0, 15).forEach((location, idx) => {
+                    const textPreview = location.text.length > 30
+                        ? location.text.substring(0, 27) + '...'
+                        : location.text;
+                    console.log(`  ${(idx + 1).toString().padStart(2)}. Queue: ${location.queueSize.toString().padStart(4)}  Token #${location.tokenIndex.toString().padStart(6)}  ${location.tokenType.padEnd(15)}  at ${location.line}:${location.column}  "${textPreview}"`);
+                });
+            }
+            else if (earlyQueues.length > 0) {
+                console.log('\nNo large token queues detected after initial parsing (Good!)');
+            }
+        }
+        console.log('\n=== End of Report ===\n');
+    }
+    printTokenStream(limit) {
+        console.log('\n=== Token Stream ===\n');
+        const tokens = limit ? this.tokenStream.slice(0, limit) : this.tokenStream;
+        tokens.forEach(token => {
+            this.logToken(token);
+        });
+        if (limit && this.tokenStream.length > limit) {
+            console.log(`\n... and ${this.tokenStream.length - limit} more tokens`);
+        }
+        console.log(`\nTotal: ${this.tokenStream.length} tokens\n`);
+    }
+    printCharacterToTokenMapping(startLine, endLine) {
+        if (!this.sourceText) {
+            console.log('\nNo source text available. Call setSourceText() before lexing.\n');
+            return;
+        }
+        console.log('\n=== Character-to-Token Mapping ===\n');
+        const lines = this.sourceText.split('\n');
+        const start = startLine !== undefined ? Math.max(0, startLine - 1) : 0;
+        const end = endLine !== undefined ? Math.min(lines.length, endLine) : lines.length;
+        for (let lineNum = start; lineNum < end; lineNum++) {
+            const line = lines[lineNum];
+            const lineTokens = this.tokenStream.filter(t => t.line === lineNum + 1);
+            console.log(`Line ${(lineNum + 1).toString().padStart(4)}: ${line}`);
+            if (lineTokens.length > 0) {
+                const charMap = new Array(line.length).fill(' ');
+                const tokenLabels = [];
+                lineTokens.forEach((token, idx) => {
+                    const char = String.fromCharCode(65 + (idx % 26));
+                    const startCol = token.column;
+                    const endCol = Math.min(token.column + token.text.length, line.length);
+                    for (let i = startCol; i < endCol; i++) {
+                        charMap[i] = char;
+                    }
+                    tokenLabels.push({
+                        col: startCol,
+                        label: `${char}=${token.type}`
+                    });
+                });
+                console.log('       ' + charMap.join(''));
+                tokenLabels.forEach(({ col, label }) => {
+                    console.log('       ' + ' '.repeat(col) + '└─ ' + label);
+                });
+            }
+            console.log('');
+        }
+    }
+    printLexerOperationSummary() {
+        console.log('\n=== Lexer Operation Summary ===\n');
+        console.log('Input Processing:');
+        console.log(`  Source characters: ${this.sourceText.length}`);
+        console.log(`  Characters tokenized: ${this.totalCharactersProcessed}`);
+        console.log(`  Peak position: ${this.peakCharacterPosition}`);
+        console.log(`  Coverage: ${((this.totalCharactersProcessed / Math.max(this.sourceText.length, 1)) * 100).toFixed(1)}%`);
+        console.log('\nToken Generation:');
+        console.log(`  Total tokens: ${this.totalTokens}`);
+        console.log(`  Unique token types: ${this.tokenTypeStats.size}`);
+        console.log(`  Average token length: ${(this.totalCharactersProcessed / Math.max(this.totalTokens, 1)).toFixed(2)} chars`);
+        console.log('\nToken Type Distribution:');
+        const topTypes = Array.from(this.tokenTypeStats.entries())
+            .sort((a, b) => b[1].count - a[1].count)
+            .slice(0, 8);
+        topTypes.forEach(([type, stats]) => {
+            const percentage = (stats.count / this.totalTokens * 100).toFixed(1);
+            const bar = '█'.repeat(Math.floor(stats.count / this.totalTokens * 40));
+            console.log(`  ${type.padEnd(18)} ${stats.count.toString().padStart(5)} (${percentage.padStart(5)}%) ${bar}`);
+        });
+        console.log('\nLexing Process:');
+        console.log(`  INDENT tokens: ${this.indentCount}`);
+        console.log(`  DEDENT tokens: ${this.dedentCount}`);
+        console.log(`  NEWLINE tokens: ${this.newlineCount}`);
+        console.log(`  Max token queue: ${this.maxQueueSize}`);
+        console.log(`  Avg token queue: ${this.queueSizeSamples.length > 0 ? (this.queueSizeSamples.reduce((a, b) => a + b, 0) / this.queueSizeSamples.length).toFixed(1) : 0}`);
+        console.log('\n=== End of Summary ===\n');
+    }
+    getRecommendations() {
+        const diagnostics = this.getDiagnostics();
+        const recommendations = [];
+        const indentationTokens = diagnostics.indentCount + diagnostics.dedentCount + diagnostics.newlineCount;
+        const indentationPercentage = (indentationTokens / diagnostics.totalTokens) * 100;
+        if (indentationPercentage > 20) {
+            recommendations.push(`High percentage of indentation tokens (${indentationPercentage.toFixed(1)}%). Consider optimizing INDENT/DEDENT/NEWLINE processing.`);
+        }
+        const earlyThreshold = Math.min(100, diagnostics.totalTokens * 0.05);
+        const laterQueues = diagnostics.largeQueueLocations.filter(loc => loc.tokenIndex > earlyThreshold);
+        if (laterQueues.length > 0 && laterQueues[0].queueSize > 100) {
+            recommendations.push(`Large token queue detected after initial parsing (max: ${laterQueues[0].queueSize} at line ${laterQueues[0].line}:${laterQueues[0].column}). This may indicate excessive lookahead or buffering in specific grammar rules.`);
+        }
+        else if (diagnostics.maxQueueSize > 200) {
+            recommendations.push(`Very large token queue detected during initial parsing (max: ${diagnostics.maxQueueSize}). This is expected for the script rule but consider if it's excessive.`);
+        }
+        const slowTokenTypes = Array.from(diagnostics.tokenTypeStats.entries())
+            .filter(([, stats]) => stats.averageTimeUs > 50)
+            .sort((a, b) => b[1].averageTimeUs - a[1].averageTimeUs);
+        if (slowTokenTypes.length > 0) {
+            slowTokenTypes.forEach(([type, stats]) => {
+                recommendations.push(`Token type '${type}' has high average generation time (${stats.averageTimeUs.toFixed(2)} μs). Review lexer rule.`);
+            });
+        }
+        const tokensPerSecond = diagnostics.totalTokens / (diagnostics.totalTimeMicroseconds / 1000000);
+        if (tokensPerSecond < 100000) {
+            recommendations.push(`Low token generation rate (${tokensPerSecond.toFixed(0)} tokens/sec). Consider lexer optimization.`);
+        }
+        return recommendations;
+    }
+}

package/dist/esm/{ComponentAnnotater.js → annotate/ComponentAnnotater.js}

@@ -1,4 +1,4 @@
-import { ComponentRefDesPrefixes } from './visitor.js';
+import { ComponentRefDesPrefixes } from './../visitor.js';
 export class ComponentAnnotater {
     counter = {};
     indexedContextPrefix = new Map();
@@ -9,20 +9,34 @@ export class ComponentAnnotater {
         }
     }
     getAnnotation(instance) {
-        const type = instance.typeProp ?? 'conn';
-        if (this.counter[type] === undefined && type.length <= 2) {
-            for (const [, value] of Object.entries(ComponentRefDesPrefixes)) {
-                if (value === type) {
-                    throw "Refdes prefix is already in use!";
+        let usePrefix;
+        let useCounterKey;
+        if (instance.hasParam('refdesPrefix')) {
+            const prefix = instance.getParam('refdesPrefix');
+            if (this.counter[prefix] === undefined) {
+                this.counter[prefix] = 1;
+            }
+            usePrefix = prefix;
+            useCounterKey = prefix;
+        }
+        else {
+            const type = instance.typeProp ?? 'conn';
+            if (this.counter[type] === undefined && type.length <= 2) {
+                for (const [, value] of Object.entries(ComponentRefDesPrefixes)) {
+                    if (value === type) {
+                        throw "Refdes prefix is already in use!";
+                    }
+                }
+                if (ComponentRefDesPrefixes[type] === undefined) {
+                    ComponentRefDesPrefixes[type] = type;
+                    this.counter[type] = 1;
                 }
             }
             if (ComponentRefDesPrefixes[type] === undefined) {
-                ComponentRefDesPrefixes[type] = type;
-                this.counter[type] = 1;
+                return null;
             }
-        }
-        if (ComponentRefDesPrefixes[type] === undefined) {
-            return null;
+            usePrefix = ComponentRefDesPrefixes[type];
+            useCounterKey = type;
         }
         let prefix = '';
         let resultRefdes = '';
@@ -39,8 +53,8 @@ export class ComponentAnnotater {
                         prefix = instance.placeHolderRefDes.replaceAll('_', '');
                     }
                     else {
-                        const { index: nextIndex, proposedName } = this.getNextRefdesCounter(ComponentRefDesPrefixes[type], this.counter[type]);
-                        this.counter[type] = nextIndex;
+                        const { index: nextIndex, proposedName } = this.getNextRefdesCounter(usePrefix, this.counter[useCounterKey]);
+                        this.counter[useCounterKey] = nextIndex;
                         prefix = proposedName;
                     }
                     this.existingRefDes.push(prefix);
@@ -53,8 +67,8 @@ export class ComponentAnnotater {
                 }
             }
             else {
-                const refdesCounter = this.getNextRefdesCounter(ComponentRefDesPrefixes[type], this.counter[type]);
-                this.counter[type] = refdesCounter.index;
+                const refdesCounter = this.getNextRefdesCounter(usePrefix, this.counter[useCounterKey]);
+                this.counter[useCounterKey] = refdesCounter.index;
                 resultRefdes = refdesCounter.proposedName;
             }
             this.existingRefDes.push(resultRefdes);

package/dist/esm/annotate/DefaultPostAnnotationCallback.js

@@ -0,0 +1,122 @@
+import { RefdesFileSuffix } from "../globals.js";
+import { RefdesOutputType } from "../helpers.js";
+import { RefdesAnnotationVisitor } from "./RefdesAnnotationVisitor.js";
+export async function DefaultPostAnnotationCallback(options, scriptData, tree, tokens, componentLinks, importedLibraries, environment) {
+    const { inputPath = null, updateSource = false, saveAnnotatedCopy = undefined, } = options;
+    if (inputPath && (updateSource || saveAnnotatedCopy !== undefined)) {
+        const sourceAnnotatedFiles = [{
+                isMainFile: true,
+                scriptData,
+                tokens,
+                tree,
+                filePath: inputPath,
+                outputType: RefdesOutputType.WithSource
+            }];
+        const externalRefdesLibraries = [];
+        for (const library of importedLibraries) {
+            let outputType = RefdesOutputType.None;
+            if (library.enableRefdesAnnotation) {
+                outputType = RefdesOutputType.WithSource;
+            }
+            else if (library.enableRefdesAnnotationFile) {
+                outputType = RefdesOutputType.CreateExternalFile;
+            }
+            if (outputType !== RefdesOutputType.None) {
+                const { libraryFilePath, libraryName, tokens: libTokens, tree: libTree } = library;
+                const libraryScriptData = await environment.readFile(libraryFilePath, { encoding: 'utf8' });
+                const annotatedFile = {
+                    tokens: libTokens,
+                    tree: libTree,
+                    filePath: libraryFilePath,
+                    scriptData: libraryScriptData,
+                    libraryName,
+                    outputType,
+                    library: library,
+                    referencedTokens: library.referencedTokens,
+                };
+                if (outputType === RefdesOutputType.CreateExternalFile) {
+                    externalRefdesLibraries.push(annotatedFile);
+                }
+                else {
+                    sourceAnnotatedFiles.push(annotatedFile);
+                }
+            }
+        }
+        for (const item of sourceAnnotatedFiles) {
+            const { scriptData, tokens, tree, filePath, libraryName, referencedTokens = [], isMainFile = false, library } = item;
+            let usePath = filePath;
+            if (isMainFile && saveAnnotatedCopy === true) {
+                const dir = environment.dirname(filePath);
+                const ext = environment.extname(filePath);
+                const basename = environment.basename(filePath, ext);
+                usePath = environment.join(dir, `${basename}.annotated${ext}`);
+            }
+            else if (isMainFile && typeof saveAnnotatedCopy === 'string') {
+                usePath = saveAnnotatedCopy;
+            }
+            let updatedScriptData = scriptData;
+            const isCachedLibrary = tokens === null && tree === null;
+            let modifications;
+            if (isCachedLibrary && referencedTokens) {
+                const updatedLines = updatedScriptData.split('\n');
+                for (const [tokens, tree] of referencedTokens) {
+                    const inputStream = tokens.tokenSource.inputStream;
+                    const scriptChunk = inputStream.getTextFromRange(0, inputStream.size);
+                    const tmpVisitor = new RefdesAnnotationVisitor(true, scriptChunk, tokens, componentLinks);
+                    tmpVisitor.visit(tree);
+                    modifications = tmpVisitor.getModifications();
+                    if (modifications.size > 0 && library && !library.writeToCache) {
+                        library.writeToCache = true;
+                    }
+                    const resultOutput = tmpVisitor.getOutput();
+                    const resultLines = resultOutput.split('\n');
+                    const replaceStartLine = tokens.get(0).line;
+                    updatedLines.splice(replaceStartLine - 1, resultLines.length, ...resultLines);
+                }
+                updatedScriptData = updatedLines.join('\n');
+            }
+            else {
+                const tmpVisitor = new RefdesAnnotationVisitor(true, scriptData, tokens, componentLinks);
+                tmpVisitor.visit(tree);
+                modifications = tmpVisitor.getModifications();
+                updatedScriptData = tmpVisitor.getOutput();
+            }
+            library && library.addRefdesModifications(modifications);
+            environment.writeFileSync(usePath, updatedScriptData);
+            let display = 'Refdes annotations';
+            if (libraryName) {
+                display += ` for library ${libraryName}`;
+            }
+            console.log(`${display} saved to ${usePath}`);
+        }
+        if (externalRefdesLibraries.length > 0) {
+            const inputDir = environment.dirname(inputPath);
+            const inputExt = environment.extname(inputPath);
+            const inputBasename = environment.basename(inputPath, inputExt);
+            const refdesFilePath = environment.join(inputDir, `${inputBasename}${RefdesFileSuffix}`);
+            const libraries = [];
+            for (const item of externalRefdesLibraries) {
+                const { scriptData, tokens, tree, filePath, libraryName } = item;
+                const tmpVisitor = new RefdesAnnotationVisitor(true, scriptData, tokens, componentLinks);
+                await tmpVisitor.visit(tree);
+                const output = tmpVisitor.getOutputForExternalRefdesFile();
+                const relativeFilePath = environment.relative(inputDir, filePath);
+                libraries.push({
+                    name: libraryName,
+                    path: relativeFilePath,
+                    items: output,
+                });
+            }
+            const sortedLibs = libraries.sort((a, b) => {
+                return a.name.localeCompare(b.name);
+            });
+            const jsonFile = {
+                format: 'v1',
+                description: 'Stores external refdes for libraries',
+                libraries: sortedLibs,
+            };
+            environment.writeFileSync(refdesFilePath, JSON.stringify(jsonFile, null, 4));
+            console.log(`External refdes annotations saved to ${refdesFilePath}`);
+        }
+    }
+}