@halospv3/hce.shared-config
Version:
Automate commit message quality, changelogs, and CI/CD releases. Its `main` entry point is a Semantic Release config. Functions and classes are exposed for customization. An ESLint config, a Commitlint config, and addl. resources for .NET projects are als
302 lines • 12.6 kB
text/typescript
import _debug from "../debug.mjs";
import { execAsync } from "../utils/execAsync.mjs";
import { NugetProjectProperties } from "./NugetProjectProperties.mjs";
import { Scope, Type } from "arktype";
import { tmpdir } from "node:os";
//#region src/dotnet/MSBuildProject.d.ts
type TemporaryDirectoryNamespace_Unix = `${ReturnType<typeof tmpdir>}/HCE.Shared/.NET/`;
type TemporaryDirectoryNamespace_Win = `${ReturnType<typeof tmpdir>}\\HCE.Shared\\.NET\\`;
declare const msbuildEvaluationOutput: Type<{
Properties?: Record<string, string> | undefined;
Items?: Record<string, {
[x: string]: string | undefined;
Identity: string;
FullPath: string;
RootDir: string;
Filename: string;
Extension: string;
RelativeDir: string;
Directory: string;
RecursiveDir: string;
ModifiedTime: string;
CreatedTime: string;
AccessedTime: string;
DefiningProjectFullPath: string;
DefiningProjectDirectory: string;
DefiningProjectName: string;
DefiningProjectExtension: string;
SubType?: string;
TargetFrameworkIdentifier?: string | undefined;
TargetPlatformMoniker?: string | undefined;
CopyUpToDateMarker?: string | undefined;
TargetPlatformIdentifier?: string | undefined;
TargetFrameworkVersion?: string | undefined;
ReferenceAssembly?: string | undefined;
}[]> | undefined;
TargetResults?: Record<string, {
Result: "Success";
Items: {
[x: string]: string | undefined;
Identity: string;
FullPath: string;
RootDir: string;
Filename: string;
Extension: string;
RelativeDir: string;
Directory: string;
RecursiveDir: string;
ModifiedTime: string;
CreatedTime: string;
AccessedTime: string;
DefiningProjectFullPath: string;
DefiningProjectDirectory: string;
DefiningProjectName: string;
DefiningProjectExtension: string;
SubType?: string | undefined;
TargetFrameworkIdentifier?: string | undefined;
TargetPlatformMoniker?: string | undefined;
CopyUpToDateMarker?: string | undefined;
TargetPlatformIdentifier?: string | undefined;
TargetFrameworkVersion?: string | undefined;
ReferenceAssembly?: string | undefined;
}[];
} | {
Result: "Failure";
Items: never[];
}> | undefined;
}>;
declare class MSBuildEvaluationOutput {
/**
* The specified properties and their values as evaluated by MSBuild Core.
* `-getProperty:{propertyName,...}`
*/
Properties?: typeof msbuildEvaluationOutput.infer.Properties;
/**
* The specified items and their values and associated metadata as evaluated
* by MSBuild Core.
* `-getItem:{itemName,...}`
*/
Items?: typeof msbuildEvaluationOutput.infer.Items;
/**
* The specified Targets and their output values as evaluated by MSBuild
* Core.
* `-getTargetResult:{targetName,...}`
*/
TargetResults?: typeof msbuildEvaluationOutput.infer.TargetResults;
/**
* @param rawMSBuildEvaluation The output of a CLI MSBuild project evaluation.
* May be the UTF-8 string-encoded JSON or the object decoded from that JSON.
*/
constructor(rawMSBuildEvaluation: Parameters<typeof JSON.parse>[0] | Parameters<typeof msbuildEvaluationOutput.from>[0]);
}
declare const EvaluationOptions: Type<{
FullName: string;
/**
* @see {@link NugetProjectProperties}
* @description
* User-defined Properties and their values.
* `{ Configuration: "Release" }` will cause the MSBuild to first set the
* Configuration property to Release before evaluating the project
* or the project's Target(s).
* ```txt
* -property:<n>=<v> Set or override these project-level properties. <n> is
* the property name, and <v> is the property value. Use a
* semicolon or a comma to separate multiple properties, or
* specify each property separately. (Short form: -p)
* Example:
* -property:WarningLevel=2;OutDir=bin\Debug\
* ```
*/
Property: Partial<{ -readonly [P in keyof NugetProjectProperties]: NugetProjectProperties[P]; }>;
Targets: readonly string[] | string[];
GetItem: readonly string[] | string[];
GetProperty: readonly string[] | string[];
GetTargetResult: readonly string[] | string[];
}>;
declare class MSBuildProject {
/**
* Properties for multi-targeting `dotnet publish` outputs.
* These are included in {@link NPPGetterNames.InstanceGettersRecursive}.
*/
static readonly MatrixProperties: readonly string[];
/**
* @param projectPath The full path of the project file or its directory. A
* relative path may be passed, but will resolve relative to the current
* working directory.
* @param includeNonPublic Include conventionally internal/private MSBuild
* targets in the result.
* @returns A string array of the project's MSBuild targets.
* @todo consider 'file' of -targets[:file]
* Prints a list of available targets without executing the
* actual build process. By default the output is written to
* the console window. If the path to an output file
* is provided that will be used instead.
* (Short form: -ts)
* Example:
* -ts:out.txt
*/
static GetTargets(projectPath: string, includeNonPublic?: boolean): Promise<string[]>;
/**
* Evaluate {@link Items}, {@link Properties}, and {@link TargetResults},
* returning them as an instance of {@link MSBuildProject}.\
* Note: MSBuild will probably fail if Restore is skipped and another
* target is specified. If you choose Pack, you must do ['Restore', 'Pack'].
* @param options The result of {@link EvaluationOptions.from}.
* @returns A promised {@link MSBuildProject} instance.
* @throws {Error} if the exec command fails -OR- the JSON parse fails -OR-
* MSBuildProject's constructor fails.
* @see {@link PackableProjectsToMSBuildProjects} for most use-cases.
*/
static Evaluate(options: typeof EvaluationOptions.inferOut): Promise<MSBuildProject>;
/**
* Evaluate multiple project paths with some default Evaluate options.
* @async
* @param projectsToPackAndPush An array of MSBuild projects' full file
* paths. If a path is a directory, files in that directory are filtered for
* `.csproj`, `.fsproj`, and `.vbproj` project files.
* See https://github.com/dotnet/sdk/blob/497f334b2862bdf98b30c00ede2fd259ea5f624d/src/Cli/dotnet/Commands/New/MSBuildEvaluation/MSBuildEvaluationResult.cs#L19-L32.\
* @returns A promised array of {@link MSBuildProject} instances.
* All known MSBuild and NuGet properties are evaluated.
* If applicable, a project's "Pack" target is evaluated.
*/
static PackableProjectsToMSBuildProjects(projectsToPackAndPush: string[]): Promise<Promise<MSBuildProject>[]>;
static fromJSON(json: string): MSBuildProject;
readonly Items: Readonly<Required<MSBuildEvaluationOutput>["Items"]>;
readonly Properties: Readonly<NugetProjectProperties>;
readonly Targets: readonly string[];
/**
* Allows appending subsequent target results.
*/
readonly TargetResults: Required<MSBuildEvaluationOutput>["TargetResults"][];
/**
* Creates an instance of MSBuildProject.
* @param opts The order-independent arguments for this constructor.
* Properties may be added or moved around in this definition without
* breaking compatibility.
* @param opts.fullPath The full path of the MSBuild project's file. This
* should have a '.csproj', '.fsproj', or '.vbproj' file extension.
* @param opts.projTargets A list of MSBuild Targets supported by the project.
* @param opts.evaluation The output of an MSBuild project evaluation. This
* comprises MSBuild Properties, Items, and Target results.
*/
constructor(opts: {
fullPath: string;
projTargets: string[];
evaluation: MSBuildEvaluationOutput;
});
}
/**
* ArkType type definitions for internal usage, but may be re-used elsewhere
* @internal
*/
declare const _InternalMSBuildEvaluationTypes: Scope<{
msbuildEvaluationOutput: {
Properties?: Record<string, string> | undefined;
Items?: Record<string, {
[x: string]: string | undefined;
Identity: string;
FullPath: string;
RootDir: string;
Filename: string;
Extension: string;
RelativeDir: string;
Directory: string;
RecursiveDir: string;
ModifiedTime: string;
CreatedTime: string;
AccessedTime: string;
DefiningProjectFullPath: string;
DefiningProjectDirectory: string;
DefiningProjectName: string;
DefiningProjectExtension: string;
SubType?: string | undefined;
TargetFrameworkIdentifier?: string | undefined;
TargetPlatformMoniker?: string | undefined;
CopyUpToDateMarker?: string | undefined;
TargetPlatformIdentifier?: string | undefined;
TargetFrameworkVersion?: string | undefined;
ReferenceAssembly?: string | undefined;
}[]> | undefined;
TargetResults?: Record<string, {
Result: "Success";
Items: {
[x: string]: string | undefined;
Identity: string;
FullPath: string;
RootDir: string;
Filename: string;
Extension: string;
RelativeDir: string;
Directory: string;
RecursiveDir: string;
ModifiedTime: string;
CreatedTime: string;
AccessedTime: string;
DefiningProjectFullPath: string;
DefiningProjectDirectory: string;
DefiningProjectName: string;
DefiningProjectExtension: string;
SubType?: string | undefined;
TargetFrameworkIdentifier?: string | undefined;
TargetPlatformMoniker?: string | undefined;
CopyUpToDateMarker?: string | undefined;
TargetPlatformIdentifier?: string | undefined;
TargetFrameworkVersion?: string | undefined;
ReferenceAssembly?: string | undefined;
}[];
} | {
Result: "Failure";
Items: never[];
}> | undefined;
};
}>;
/**
* Use this in your catch statement or .catch call to return `undefined` when
* a "file in use by another process" (i.e. EBUSY/ERROR_SHARING_VIOLATION) error is reported.
* @param error Probably an Error object
* @returns `undefined` if file in use by another process
*/
declare function catchEBUSY(error: unknown): undefined;
/**
*
* Use this in your catch statement or .catch call to return `undefined` when
* MSBuild error CSC2012 (e.g. "file in use by another process") is reported.
* @param error Probably an Error object
* @returns `undefined` if CSC2012 (file in use by another process) occurs
* @deprecated Use {@link catchEBUSY}.
*/
declare function catchCsc2012(error: unknown): undefined;
/**
*
* @returns A Promise of execAsync's output object.
* @param root0 structured parameters object
* @param root0.commandLine The command line to try and retry
* @param root0.taskVerb Used in debug messages e.g. ```
* const debug_MSBP = debug.extend('MSBuildProject');
* debug_MSBP.enabled = debug.enabled;
* const output = await loopTryDotnetCommand({ customDebugger: debug_MSBP, ... });
* ```
* @param root0.customDebugger e.g. `debug.extend('Evaluate)`
* @param root0.projectName The filename (sans extension) or AssemblyName of the project e.g. `path.basename(fullPath, path.extname(fullPath))`
* @param root0.timeoutMilliseconds The maximum time spent (re)trying the command.
* Warning! {@link totalMilliseconds} may be significantly greater than {@link timeoutMilliseconds}!
* e.g.
* `325_000 <=300_000` (5m25s vs 5m)
* `378_000 <=360_000` (6m18s vs 6m),
* `630_000 <=600_000` (10m30s vs 10m)
* `1225_000 <=1200_000` (20m25s vs 20m)
* `2415_000 <=2400_000` (40m15s vs 40m)
* `2556_000 <=2485_000` (42m36s vs 41m25s; 71 seconds over)
* @throws {Error} when retry limit is reached or an unhandled exception occurs.
* File-in-use errors are _supposed_ to be ignored and retried.
*/
declare function loopTryDotnetCommand({ commandLine, customDebugger, projectName, taskVerb, timeoutMilliseconds: maximumTime }: {
commandLine: string;
customDebugger: typeof _debug;
projectName: string;
taskVerb?: string | undefined;
timeoutMilliseconds: number;
}): Promise<Awaited<ReturnType<typeof execAsync>>>;
//#endregion
export { EvaluationOptions, MSBuildEvaluationOutput, MSBuildProject, TemporaryDirectoryNamespace_Unix, TemporaryDirectoryNamespace_Win, _InternalMSBuildEvaluationTypes, catchCsc2012, catchEBUSY, loopTryDotnetCommand };
//# sourceMappingURL=MSBuildProject.d.mts.map