refactor(fs): rename read functions to be more specific, add docstrings

packages/amazonq/test/unit/amazonqGumby/humanInTheLoopManager.test.ts

@@ -36,7 +36,7 @@ describe('HumanInTheLoopManager', async function () {
         )
         const outputPathResult = path.join(outputDirectoryPath, 'pom.xml')
         assertEqualPaths(newPomFilePath.fsPath, outputPathResult)
-        const newPomFileContents = await fs.readFileAsString(newPomFilePath.path)
+        const newPomFileContents = await fs.readFileText(newPomFilePath.path)
         assert.strictEqual(
             stripStringWhitespace(newPomFileContents),
             stripStringWhitespace(`<?xml version="1.0" encoding="UTF-8"?>

packages/amazonq/test/unit/validation.test.ts

@@ -23,7 +23,7 @@ describe('package validations', function () {
      */
     it('has synced contributes.icons with core/package.json', async function () {
         const corePackageJson = JSON.parse(
-            await fs.readFileAsString(path.resolve(__dirname, '../../../../core/package.json'))
+            await fs.readFileText(path.resolve(__dirname, '../../../../core/package.json'))
         )
         assert.deepStrictEqual(packageJson.contributes.icons, corePackageJson.contributes.icons)
     })

packages/core/src/amazonq/lsp/lspController.ts

@@ -133,7 +133,7 @@ export class LspController {
     }
 
     async getFileSha384(filePath: string): Promise<string> {
-        const fileBuffer = await fs.readFile(filePath)
+        const fileBuffer = await fs.readFileBytes(filePath)
         const hash = crypto.createHash('sha384')
         hash.update(fileBuffer)
         return hash.digest('hex')

packages/core/src/auth/credentials/sharedCredentials.ts

@@ -230,15 +230,15 @@ async function loadConfigFile(configUri?: vscode.Uri): Promise<ReturnType<typeof
         return []
     }
 
-    return parseIni(await fs.readFileAsString(configUri), configUri)
+    return parseIni(await fs.readFileText(configUri), configUri)
 }
 
 async function loadCredentialsFile(credentialsUri?: vscode.Uri): Promise<ReturnType<typeof parseIni>> {
     if (!credentialsUri || !(await fs.exists(credentialsUri))) {
         return []
     }
 
-    return parseIni(await fs.readFileAsString(credentialsUri), credentialsUri)
+    return parseIni(await fs.readFileText(credentialsUri), credentialsUri)
 }
 
 /**

packages/core/src/auth/sso/server.ts

@@ -218,7 +218,7 @@ export class AuthSSOServer {
 
     private async loadResource(res: http.ServerResponse, resourcePath: string) {
         try {
-            const file = await fs.readFile(resourcePath)
+            const file = await fs.readFileBytes(resourcePath)
             res.writeHead(200)
             res.end(file)
         } catch (e) {

packages/core/src/awsService/cdk/explorer/cdkProject.ts

@@ -18,7 +18,7 @@ export interface CdkAppLocation {
 }
 
 export async function getApp(location: CdkAppLocation): Promise<CdkApp> {
-    const constructTree = JSON.parse(await fs.readFileAsString(location.treeUri)) as ConstructTree
+    const constructTree = JSON.parse(await fs.readFileText(location.treeUri)) as ConstructTree
 
     return { location, constructTree }
 }

packages/core/src/awsService/ec2/sshKeyPair.ts

@@ -68,7 +68,7 @@ export class SshKeyPair {
     }
 
     public async getPublicKey(): Promise<string> {
-        const contents = await fs.readFileAsString(this.publicKeyPath)
+        const contents = await fs.readFileText(this.publicKeyPath)
         return contents
     }
 

packages/core/src/awsService/iot/commands/createPolicy.ts

@@ -66,7 +66,7 @@ export async function getPolicyDocument(): Promise<Uint8Array | undefined> {
 
     let data: Uint8Array
     try {
-        data = await fs.readFile(policyLocation.fsPath)
+        data = await fs.readFileBytes(policyLocation.fsPath)
     } catch (e) {
         getLogger().error('Failed to read policy document: %s', e)
         void showViewLogsMessage(localize('AWS.iot.createPolicy.error', 'Failed to read policy document'))

packages/core/src/codewhisperer/service/transformByQ/humanInTheLoopManager.ts

@@ -64,7 +64,7 @@ export class HumanInTheLoopManager {
     }
 
     public getDependencyListXmlOutput = async () =>
-        await fs.readFileAsString(path.join(this.tmpDependencyListDir, this.localPathToXmlDependencyList))
+        await fs.readFileText(path.join(this.tmpDependencyListDir, this.localPathToXmlDependencyList))
 
     public createPomFileCopy = async (outputDirectoryPath: string, pomFileVirtualFileReference: vscode.Uri) => {
         const newPomCopyRef = await createPomCopy(outputDirectoryPath, pomFileVirtualFileReference, 'pom.xml')

packages/core/src/codewhisperer/service/transformByQ/transformApiHandler.ts

@@ -177,7 +177,7 @@ export async function stopJob(jobId: string) {
 }
 
 export async function uploadPayload(payloadFileName: string, uploadContext?: UploadContext) {
-    const buffer = Buffer.from(await fs.readFile(payloadFileName))
+    const buffer = Buffer.from(await fs.readFileBytes(payloadFileName))
     const sha256 = getSha256(buffer)
 
     throwIfCancelled()

packages/core/src/codewhisperer/service/transformByQ/transformFileHandler.ts

@@ -43,7 +43,7 @@ export async function createPomCopy(
     fileName: string
 ): Promise<vscode.Uri> {
     const newFilePath = path.join(dirname, fileName)
-    const pomFileContents = await fs.readFileAsString(pomFileVirtualFileReference.fsPath)
+    const pomFileContents = await fs.readFileText(pomFileVirtualFileReference.fsPath)
     const directoryExits = await fs.exists(dirname)
     if (!directoryExits) {
         await fs.mkdir(dirname)
@@ -53,15 +53,15 @@ export async function createPomCopy(
 }
 
 export async function replacePomVersion(pomFileVirtualFileReference: vscode.Uri, version: string, delimiter: string) {
-    const pomFileText = await fs.readFileAsString(pomFileVirtualFileReference.fsPath)
+    const pomFileText = await fs.readFileText(pomFileVirtualFileReference.fsPath)
     const pomFileTextWithNewVersion = pomFileText.replace(delimiter, version)
     writeFileSync(pomFileVirtualFileReference.fsPath, pomFileTextWithNewVersion)
 }
 
 export async function getJsonValuesFromManifestFile(
     manifestFileVirtualFileReference: vscode.Uri
 ): Promise<IManifestFile> {
-    const manifestFileContents = await fs.readFileAsString(manifestFileVirtualFileReference.fsPath)
+    const manifestFileContents = await fs.readFileText(manifestFileVirtualFileReference.fsPath)
     const jsonValues = JSON.parse(manifestFileContents.toString())
     return {
         hilCapability: jsonValues?.hilType,
@@ -136,7 +136,7 @@ async function addDiagnosticOverview(
 
 export async function getCodeIssueSnippetFromPom(pomFileVirtualFileReference: vscode.Uri) {
     // TODO[gumby]: not great that we read this file multiple times
-    const pomFileContents = await fs.readFileAsString(pomFileVirtualFileReference.fsPath)
+    const pomFileContents = await fs.readFileText(pomFileVirtualFileReference.fsPath)
 
     const dependencyRegEx = /<dependencies\b[^>]*>(.*?)<\/dependencies>/ms
     const match = dependencyRegEx.exec(pomFileContents)

packages/core/src/codewhisperer/util/supplementalContext/crossFileContextUtil.ts

@@ -199,7 +199,7 @@ function linkChunks(chunks: Chunk[]) {
 export async function splitFileToChunks(filePath: string, chunkSize: number): Promise<Chunk[]> {
     const chunks: Chunk[] = []
 
-    const fileContent = (await fs.readFileAsString(filePath)).trimEnd()
+    const fileContent = (await fs.readFileText(filePath)).trimEnd()
     const lines = fileContent.split('\n')
 
     for (let i = 0; i < lines.length; i += chunkSize) {

packages/core/src/codewhisperer/util/supplementalContext/utgUtils.ts

@@ -116,7 +116,7 @@ async function generateSupplementalContextFromFocalFile(
     strategy: UtgStrategy,
     cancellationToken: vscode.CancellationToken
 ): Promise<CodeWhispererSupplementalContextItem[]> {
-    const fileContent = await fs.readFileAsString(vscode.Uri.parse(filePath!).fsPath)
+    const fileContent = await fs.readFileText(vscode.Uri.parse(filePath!).fsPath)
 
     // DO NOT send code chunk with empty content
     if (fileContent.trim().length === 0) {
@@ -136,7 +136,7 @@ async function findSourceFileByContent(
     languageConfig: utgLanguageConfig,
     cancellationToken: vscode.CancellationToken
 ): Promise<string | undefined> {
-    const testFileContent = await fs.readFileAsString(editor.document.fileName)
+    const testFileContent = await fs.readFileText(editor.document.fileName)
     const testElementList = extractFunctions(testFileContent, languageConfig.functionExtractionPattern)
 
     throwIfCancelled(cancellationToken)
@@ -161,7 +161,7 @@ async function findSourceFileByContent(
     for (const filePath of relevantFilePaths) {
         throwIfCancelled(cancellationToken)
 
-        const fileContent = await fs.readFileAsString(filePath)
+        const fileContent = await fs.readFileText(filePath)
         const elementList = extractFunctions(fileContent, languageConfig.functionExtractionPattern)
         elementList.push(...extractClasses(fileContent, languageConfig.classExtractionPattern))
         const matchCount = countSubstringMatches(elementList, testElementList)

packages/core/src/dev/codecatalyst.ts

@@ -217,7 +217,7 @@ async function installVsix(
     if (path.extname(resp) !== '.vsix') {
         progress.report({ message: 'Copying extension...' })
 
-        const packageData = await fs.readFileAsString(path.join(resp, 'package.json'))
+        const packageData = await fs.readFileText(path.join(resp, 'package.json'))
         const targetManfiest: typeof manifest = JSON.parse(packageData)
         const destName = `${extPath}/${extId}-${targetManfiest.version}`
         const source = `${resp}${path.sep}`

packages/core/src/lambda/commands/uploadLambda.ts

@@ -419,7 +419,7 @@ async function runUploadLambdaZipFile(lambda: LambdaFunction, zipFileUri: vscode
             cancellable: false,
         },
         async (progress) => {
-            const zipFile = await fs.readFile(zipFileUri.fsPath).catch((err) => {
+            const zipFile = await fs.readFileBytes(zipFileUri.fsPath).catch((err) => {
                 throw new ToolkitError('Failed to read zip', { cause: err })
             })
             return await uploadZipBuffer(lambda, zipFile, progress)
@@ -514,7 +514,7 @@ export async function findApplicationJsonFile(
 export async function getFunctionNames(file: vscode.Uri, region: string): Promise<string[] | undefined> {
     try {
         const names: string[] = []
-        const appData = JSON.parse(await fs.readFileAsString(file.fsPath))
+        const appData = JSON.parse(await fs.readFileText(file.fsPath))
         if (appData['Functions']) {
             const functions = Object.keys(appData['Functions'])
             if (functions) {

packages/core/src/shared/credentials/userCredentialsUtils.ts

@@ -92,7 +92,7 @@ export class UserCredentialsUtils {
         const contents = credentialsContext ? ['', createNewCredentialsFile(credentialsContext)] : []
 
         if (await fs.exists(dest)) {
-            contents.unshift(await fs.readFileAsString(dest))
+            contents.unshift(await fs.readFileText(dest))
         } else {
             contents.unshift(header)
         }

packages/core/src/shared/extensionStartup.ts

@@ -60,7 +60,7 @@ export async function createQuickStartWebview(
     const baseTemplateFn = _.template(BaseTemplates.simpleHtml)
 
     const htmlBody = convertExtensionRootTokensToPath(
-        await fs.readFileAsString(path.join(context.extensionPath, actualPage)),
+        await fs.readFileText(path.join(context.extensionPath, actualPage)),
         context.extensionPath,
         view.webview
     )

packages/core/src/shared/filesystemUtilities.ts

@@ -74,7 +74,7 @@ export async function fileExists(p: string): Promise<boolean> {
  * @deprecated use {@link fs} exist methods instead.
  */
 export async function readFileAsString(pathLike: string): Promise<string> {
-    return fs.readFileAsString(pathLike)
+    return fs.readFileText(pathLike)
 }
 
 /**

packages/core/src/shared/fs/fs.ts

@@ -105,8 +105,12 @@ export class FileSystem {
         return vfs.createDirectory(uri).then(undefined, errHandler)
     }
 
-    // TODO: rename to readFileBytes()?
-    async readFile(path: Uri | string): Promise<Uint8Array> {
+    /**
+     * Read file into byte array.
+     * @param path uri or path to file.
+     * @returns byte content of file.
+     */
+    async readFileBytes(path: Uri | string): Promise<Uint8Array> {
         const uri = toUri(path)
         const errHandler = createPermissionsErrorHandler(this.isWeb, uri, 'r**')
 
@@ -116,11 +120,15 @@ export class FileSystem {
 
         return vfs.readFile(uri).then(undefined, errHandler)
     }
-
-    // TODO: rename to readFile()?
-    async readFileAsString(path: Uri | string, decoder: TextDecoder = FileSystem.#decoder): Promise<string> {
+    /**
+     * Read file and convert the resulting bytes to a string.
+     * @param path uri or path to file.
+     * @param decoder decoder to be used, defaults to UTF-8
+     * @returns string of decoded text.
+     */
+    async readFileText(path: Uri | string, decoder: TextDecoder = FileSystem.#decoder): Promise<string> {
         const uri = toUri(path)
-        const bytes = await this.readFile(uri)
+        const bytes = await this.readFileBytes(uri)
         return decoder.decode(bytes)
     }
 
@@ -131,7 +139,9 @@ export class FileSystem {
     async appendFile(path: Uri | string, content: Uint8Array | string): Promise<void> {
         path = toUri(path)
 
-        const currentContent: Uint8Array = (await this.existsFile(path)) ? await this.readFile(path) : new Uint8Array(0)
+        const currentContent: Uint8Array = (await this.existsFile(path))
+            ? await this.readFileBytes(path)
+            : new Uint8Array(0)
         const currentLength = currentContent.length
 
         const newContent = this.#toBytes(content)
@@ -143,7 +153,12 @@ export class FileSystem {
 
         return this.writeFile(path, finalContent)
     }
-
+    /**
+     * Checks if file or folder exists.
+     * @param path path to check.
+     * @param fileType optional assert that path contains certain filetype.
+     * @returns if path exists and matches filetype.
+     */
     async exists(path: Uri | string, fileType?: vscode.FileType): Promise<boolean> {
         if (path === undefined || path === '') {
             return false
@@ -291,6 +306,12 @@ export class FileSystem {
         await write(uri)
     }
 
+    /**
+     * Rename a file or folder.
+     * @param oldPath
+     * @param newPath
+     * @returns
+     */
     async rename(oldPath: vscode.Uri | string, newPath: vscode.Uri | string) {
         const oldUri = toUri(oldPath)
         const newUri = toUri(newPath)
@@ -455,7 +476,12 @@ export class FileSystem {
 
         return await vfs.readDirectory(path)
     }
-
+    /**
+     * Copy target file or directory
+     * @param source
+     * @param target
+     * @returns
+     */
     async copy(source: vscode.Uri | string, target: vscode.Uri | string): Promise<void> {
         const sourcePath = toUri(source)
         const targetPath = toUri(target)
@@ -634,7 +660,7 @@ export class FileSystem {
             return fallback
         }
     }
-
+    // Defaults to UTF-8 encoding/decoding.
     static readonly #decoder = new TextDecoder()
     static readonly #encoder = new TextEncoder()
 

packages/core/src/shared/resourcefetcher/fileResourceFetcher.ts

@@ -18,7 +18,7 @@ export class FileResourceFetcher implements ResourceFetcher {
     public async get(): Promise<string | undefined> {
         try {
             this.logger.verbose('loading file resource: "%s"', this.filepath)
-            return await fs.readFileAsString(this.filepath)
+            return await fs.readFileText(this.filepath)
         } catch (err) {
             this.logger.verbose('failed to load file resource: "%s": %s', this.filepath, (err as Error).message)
             return undefined

packages/core/src/shared/sam/config.ts

@@ -74,7 +74,7 @@ export class SamConfig {
     }
 
     public static async fromUri(uri: vscode.Uri) {
-        const contents = await fs.readFileAsString(uri)
+        const contents = await fs.readFileText(uri)
         const config = await parseConfig(contents)
 
         return new this(uri, config)

packages/core/src/shared/sam/localLambdaRunner.ts

@@ -307,7 +307,7 @@ export async function runLambdaFunction(
         const payload =
             config.eventPayloadFile === undefined
                 ? undefined
-                : JSON.parse(await fs.readFileAsString(config.eventPayloadFile))
+                : JSON.parse(await fs.readFileText(config.eventPayloadFile))
 
         apiRequest = requestLocalApi(timer, config.api!, config.apiPort!, payload)
     }
@@ -594,7 +594,7 @@ export async function makeJsonFiles(config: SamLaunchRequestArgs): Promise<void>
     if (payloadPath) {
         const fullpath = tryGetAbsolutePath(config.workspaceFolder, payloadPath)
         try {
-            JSON.parse(await fs.readFileAsString(fullpath))
+            JSON.parse(await fs.readFileText(fullpath))
         } catch (e) {
             throw Error(`Invalid JSON in payload file: ${payloadPath}`)
         }

packages/core/src/shared/telemetry/telemetryService.ts

@@ -319,7 +319,7 @@ export class DefaultTelemetryService {
 
                 return []
             }
-            const input = JSON.parse(await fs.readFileAsString(cachePath))
+            const input = JSON.parse(await fs.readFileText(cachePath))
             const events = filterTelemetryCacheEvents(input)
 
             return events

packages/core/src/shared/ui/common/variablesPrompter.ts

@@ -72,7 +72,7 @@ export function createVariablesPrompter(
                 throw new Error('Closed dialog')
             }
             const path = resp[0].fsPath
-            const contents = await fs.readFile(path)
+            const contents = await fs.readFileBytes(path)
             return parseEnvFile(contents.toString())
         } catch (err) {
             if ((err as Error).message !== 'Closed dialog') {

packages/core/src/shared/utilities/cacheUtils.ts

@@ -112,7 +112,7 @@ export function createDiskCache<V, K>(
             const target = mapKey(key)
 
             try {
-                const result = JSON.parse(await fs.readFileAsString(target))
+                const result = JSON.parse(await fs.readFileText(target))
                 log('loaded', key)
                 return result
             } catch (error) {