core-service.ts

import{ApplicationError}from'@theia/core/lib/common/application-error';
importtype{CancellationToken}from'@theia/core/lib/common/cancellation';
import{nls}from'@theia/core/lib/common/nls';
importtype{
Location,
Position,
Range,
}from'@theia/core/shared/vscode-languageserver-protocol';
importtype{CompileSummaryasApiCompileSummary}from'vscode-arduino-api';
importtype{BoardUserField,Installable}from'../../common/protocol/';
import{PortIdentifier,Programmer,isPortIdentifier}from'./boards-service';
importtype{IndexUpdateSummary}from'./notification-service';
importtype{Sketch}from'./sketches-service';

exportconstCompilerWarningLiterals=[
'None',
'Default',
'More',
'All',
]asconst;
exporttypeCompilerWarnings=(typeofCompilerWarningLiterals)[number];
exportnamespaceCompilerWarnings{
exportfunctionlabelOf(warning: CompilerWarnings): string{
returnCompilerWarningLabels[warning];
}
constCompilerWarningLabels: Record<CompilerWarnings,string>={
None: nls.localize('arduino/core/compilerWarnings/none','None'),
Default: nls.localize('arduino/core/compilerWarnings/default','Default'),
More: nls.localize('arduino/core/compilerWarnings/more','More'),
All: nls.localize('arduino/core/compilerWarnings/all','All'),
};
}
exportnamespaceCoreError{
exportinterfaceErrorLocationRef{
readonlymessage: string;
readonlylocation: Location;
readonlydetails?: string;
}
exportnamespaceErrorLocationRef{
exportfunctionequals(
left: ErrorLocationRef,
right: ErrorLocationRef
): boolean{
return(
left.message===right.message&&
left.details===right.details&&
equalsLocation(left.location,right.location)
);
}
functionequalsLocation(left: Location,right: Location): boolean{
returnleft.uri===right.uri&&equalsRange(left.range,right.range);
}
functionequalsRange(left: Range,right: Range): boolean{
return(
equalsPosition(left.start,right.start)&&
equalsPosition(left.end,right.end)
);
}
functionequalsPosition(left: Position,right: Position): boolean{
returnleft.character===right.character&&left.line===right.line;
}
}
exportinterfaceErrorLocationextendsErrorLocationRef{
/**
 * The range of the error location source from the CLI output.
 */
readonlyrangesInOutput: Range[];// The same error might show up multiple times in the CLI output: https://github.com/arduino/arduino-cli/issues/1761
}
exportconstCodes={
Verify: 4001,
Upload: 4002,
UploadUsingProgrammer: 4003,
BurnBootloader: 4004,
UploadRequiresProgrammer: 4005,
};
exportconstVerifyFailed=declareCoreError(Codes.Verify);
exportconstUploadFailed=declareCoreError(Codes.Upload);
exportconstUploadUsingProgrammerFailed=declareCoreError(
Codes.UploadUsingProgrammer
);
exportconstBurnBootloaderFailed=declareCoreError(Codes.BurnBootloader);
exportconstUploadRequiresProgrammer=declareCoreError(
Codes.UploadRequiresProgrammer
);

exportfunctionis(
error: unknown
): error is ApplicationError<number,ErrorLocation[]>{
return(
errorinstanceofError&&
ApplicationError.is(error)&&
Object.values(Codes).includes(error.code)
);
}
functiondeclareCoreError(
code: number
): ApplicationError.Constructor<number,ErrorLocation[]>{
returnApplicationError.declare(
code,
(message: string,data: ErrorLocation[])=>{
return{
 data,
 message,
};
}
);
}
}

exportinterfaceInstalledPlatformReference{
readonlyid: string;
readonlyversion: Installable.Version;
/**
 * Absolute filesystem path.
 */
readonlyinstallDir: string;
readonlypackageUrl: string;
}

exportinterfaceExecutableSectionSize{
readonlyname: string;
readonlysize: number;
readonlymaxSize: number;
}

exportinterfaceCompileSummary{
readonlybuildPath: string;
/**
 * To be compatible with the `vscode-arduino-tools` API.
 * @deprecated Use `buildPath` instead. Use Theia or VS Code URI to convert to an URI string on the client side.
 */
readonlybuildOutputUri: string;
readonlyusedLibraries: ApiCompileSummary['usedLibraries'];
readonlyexecutableSectionsSize: ExecutableSectionSize[];
readonlyboardPlatform?: InstalledPlatformReference|undefined;
readonlybuildPlatform?: InstalledPlatformReference|undefined;
readonlybuildProperties: string[];
}

exportfunctionisCompileSummary(arg: unknown): arg is CompileSummary{
return(
Boolean(arg)&&
typeofarg==='object'&&
(<CompileSummary>arg).buildPath!==undefined&&
typeof(<CompileSummary>arg).buildPath==='string'&&
(<CompileSummary>arg).buildOutputUri!==undefined&&
typeof(<CompileSummary>arg).buildOutputUri==='string'&&
(<CompileSummary>arg).executableSectionsSize!==undefined&&
Array.isArray((<CompileSummary>arg).executableSectionsSize)&&
(<CompileSummary>arg).usedLibraries!==undefined&&
Array.isArray((<CompileSummary>arg).usedLibraries)&&
(<CompileSummary>arg).buildProperties!==undefined&&
Array.isArray((<CompileSummary>arg).buildProperties)
);
}

exportinterfaceUploadResponse{
readonlyportAfterUpload: PortIdentifier;
}
exportfunctionisUploadResponse(arg: unknown): arg is UploadResponse{
return(
Boolean(arg)&&
typeofarg==='object'&&
isPortIdentifier((<UploadResponse>arg).portAfterUpload)
);
}

exportconstCoreServicePath='/services/core-service';
exportconstCoreService=Symbol('CoreService');
exportinterfaceCoreService{
compile(
options: CoreService.Options.Compile,
cancellationToken?: CancellationToken
): Promise<CompileSummary|undefined>;
upload(
options: CoreService.Options.Upload,
cancellationToken?: CancellationToken
): Promise<UploadResponse>;
burnBootloader(
options: CoreService.Options.Bootloader,
cancellationToken?: CancellationToken
): Promise<void>;
/**
 * Refreshes the underling core gRPC client for the Arduino CLI.
 */
refresh(): Promise<void>;
/**
 * Updates the index of the given index types and refreshes (`init`) the underlying core gRPC client.
 * If `types` is empty, only the refresh part will be executed.
 */
updateIndex({ types }: {types: IndexType[]}): Promise<void>;
/**
 * If the IDE2 detects invalid or missing indexes on core client init,
 * IDE2 tries to update the indexes before the first frontend connects.
 * Use this method to determine whether the backend has already updated
 * the indexes before updating them.
 *
 * If yes, the connected frontend can update the local storage with the most
 * recent index update date-time for a particular index type,
 * and IDE2 can avoid the double indexes update.
 */
indexUpdateSummaryBeforeInit(): Promise<Readonly<IndexUpdateSummary>>;
}

exportconstIndexTypeLiterals=['platform','library']asconst;
exporttypeIndexType=(typeofIndexTypeLiterals)[number];
exportnamespaceIndexType{
exportfunctionis(arg: unknown): arg is IndexType{
return(
typeofarg==='string'&&IndexTypeLiterals.includes(argasIndexType)
);
}
exportconstAll: IndexType[]=IndexTypeLiterals.filter(is);
}

exportnamespaceCoreService{
exportnamespaceOptions{
exportinterfaceBase{
readonlyfqbn?: string|undefined;
readonlyverbose: boolean;// TODO: (API) why not optional with a default false?
readonlyprogressId?: string;
}
exportinterfaceSketchBased{
readonlysketch: Sketch;
}
exportinterfaceBoardBased{
readonlyport?: PortIdentifier;
readonlyprogrammer?: Programmer|undefined;
/**
 * For the _Verify after upload_ setting.
 */
readonlyverify: boolean;// TODO: (API) why not optional with false as the default value?
}
exportinterfaceCompileextendsBase,SketchBased{
readonlyoptimizeForDebug: boolean;// TODO: (API) make this optional
readonlysourceOverride: Record<string,string>;// TODO: (API) make this optional
readonlyexportBinaries?: boolean;
readonlycompilerWarnings?: CompilerWarnings;
}
exportinterfaceUploadextendsBase,SketchBased,BoardBased{
readonlyuserFields: BoardUserField[];
readonlyusingProgrammer?: boolean;
}
exportinterfaceBootloaderextendsBase,BoardBased{}
}
}