@servicenow/sdk-build-core 3.0.3 → 4.0.0

package/src/formatter.ts

@@ -0,0 +1,58 @@
+import * as typescriptPrettierPlugin from 'prettier/plugins/typescript.js'
+import * as estreePrettierPlugin from 'prettier/plugins/estree.js'
+import { format } from 'prettier/standalone'
+import type { FileSystem } from './fs'
+import { path } from './path'
+import type { Options } from 'prettier'
+import { resolveConfig } from './prettier/config-loader'
+import { JSON5 } from './json'
+
+export class Formatter {
+    private readonly cache: Map<string, Options | null> = new Map()
+
+    constructor(private readonly fs: FileSystem) {}
+
+    public resetCache(): void {
+        this.cache.clear()
+    }
+
+    public async format(text: string, filePath: string): Promise<string> {
+        let config = await resolveConfig(filePath, this.fs, this.cache)
+
+        if (!config) {
+            config = {
+                trailingComma: 'es5',
+                singleQuote: true,
+                printWidth: 120,
+                tabWidth: 4,
+                semi: false,
+            }
+        }
+
+        const ext = path.extname(filePath)
+        if (ext === '.json') {
+            return this.formatJson(text, config)
+        }
+
+        return this.formatTypescript(text, config)
+    }
+
+    public async formatTypescript(text: string, options: Options): Promise<string> {
+        return format(sanitizeText(text), {
+            plugins: [typescriptPrettierPlugin, estreePrettierPlugin],
+            parser: 'typescript',
+            ...options,
+        })
+    }
+
+    public formatJson(jsonText: string, options: Options): string {
+        return JSON.stringify(JSON5.parse(jsonText), null, options.tabWidth ?? 2)
+    }
+}
+
+/**
+ * LS & PS characters are not supported by prettier, so replacing them with space
+ */
+function sanitizeText(fileText: string): string {
+    return fileText.replace(/[\u2028\u2029]/g, ' ')
+}

package/src/fs.ts

@@ -0,0 +1,438 @@
+import { path } from './path'
+import noop from 'lodash/noop'
+import { ts } from './typescript'
+import * as fg from 'fast-glob'
+import { Writable, Readable } from 'readable-stream'
+
+/**
+ * A file system API based on a subset of the `fs` module from Node.js.
+ */
+export interface FileSystem {
+    /**
+     * Synchronously deletes the file or directory at the provided path.
+     */
+    rmSync(path: string, options?: { recursive?: boolean; force?: boolean }): void
+
+    /**
+     * Synchronously retrieves the status of the file or directory at the provided path.
+     */
+    statSync(path: string): FileSystem.Stats
+
+    /**
+     * Synchronously retrieves the status of the file or directory at the provided path. Does
+     * not dereference symbolic links.
+     */
+    lstatSync(path: string): FileSystem.Stats
+
+    /**
+     * Synchronously computes the canonical path by resolving `.`, `..` and symbolic links.
+     */
+    realpathSync(path: string): string
+
+    /**
+     * Synchronously creates a directory at the provided path.
+     *
+     * If `options.recursive` is `true`, the full path will be created including any missing
+     * parent directories, and the path of the first directory created will be returned.
+     * Otherwise, returns `undefined`.
+     */
+    mkdirSync(path: string): void
+    mkdirSync(path: string, options: { recursive: true }): string | undefined
+    mkdirSync(path: string, options?: { recursive: boolean }): string | undefined
+
+    /**
+     * Synchronously renames the file or directory at the old path to the new path.
+     */
+    renameSync(oldPath: string, newPath: string): void
+
+    /**
+     * Synchronously reads the contents of the directory at the provided path.
+     *
+     * If `options.withFileTypes` is `true`, returns the contents as an array of `Entry`
+     * objects. Otherwise, returns the contents as an array of strings containing the names
+     * of each entry.
+     */
+    readdirSync(path: string): string[]
+    readdirSync(path: string, options: { withFileTypes: true }): FileSystem.Entry[]
+    readdirSync(path: string, options?: { withFileTypes: boolean }): string[] | FileSystem.Entry[]
+
+    /**
+     * Synchronously reads the contents of the file at the provided path.
+     *
+     * If `options.encoding` is provided, the contents will be returned as a string. Otherwise,
+     * the contents will be returned as a `Buffer`.
+     */
+    readFileSync(path: string, options?: { flag: 'r' }): Buffer
+    readFileSync(path: string, options: { encoding: FileSystem.Encoding; flag?: 'r' }): string
+    readFileSync(path: string, options?: { encoding?: FileSystem.Encoding; flag?: 'r' }): string | Buffer
+
+    /**
+     * Synchronously writes the provided content to the file at the provided path.
+     */
+    writeFileSync(
+        path: string,
+        content: string | NodeJS.ArrayBufferView,
+        options?: { encoding: FileSystem.Encoding }
+    ): void
+
+    /**
+     * Synchronously copies the file at the source path to the destination path.
+     */
+    copyFileSync(srcPath: string, destPath: string): void
+
+    /**
+     * Synchronously checks if the file or directory at the provided path is accessible. If it
+     * is accessible, the method does nothing. If it is not accessible, an error is thrown.
+     */
+    accessSync(path: string): void
+}
+
+export namespace FileSystem {
+    export type Entry = {
+        name: string
+        isFile(): boolean
+        isDirectory(): boolean
+        isSymbolicLink(): boolean
+        isCharacterDevice(): boolean
+        isBlockDevice(): boolean
+        isSocket(): boolean
+        isFIFO(): boolean
+    }
+
+    export type Stats = {
+        isFile(): boolean
+        isDirectory(): boolean
+        isSymbolicLink(): boolean
+        isCharacterDevice(): boolean
+        isBlockDevice(): boolean
+        isSocket(): boolean
+        isFIFO(): boolean
+    }
+
+    export type Encoding = 'utf-8' | 'binary'
+
+    /**
+     * Synchronously copies the file or directory at the source path to the destination
+     * path. If the source path is a directory, only its contents will be copied, not the
+     * directory itself. If the source path is a file, the destination path cannot be a
+     * directory.
+     *
+     * If `options.filter` is provided, only entries for which the filter returns `true`
+     * will be copied.
+     */
+    export function copySync(
+        fs: FileSystem,
+        srcPath: string,
+        destPath: string,
+        options?: {
+            filter(src: string): boolean
+        }
+    ) {
+        if (fs.statSync(srcPath).isDirectory()) {
+            fs.readdirSync(srcPath, { withFileTypes: true })
+                .filter((file) => options?.filter(file.name) ?? true)
+                .forEach((file) => copySync(fs, path.join(srcPath, file.name), path.join(destPath, file.name), options))
+        } else {
+            if (!FileSystem.existsSync(fs, path.dirname(destPath))) {
+                fs.mkdirSync(path.dirname(destPath), { recursive: true })
+            }
+            fs.copyFileSync(srcPath, destPath)
+        }
+    }
+
+    /**
+     * Synchronously checks if the file or directory at the provided path exists.
+     */
+    export function existsSync(fs: FileSystem, path: string): boolean {
+        try {
+            fs.accessSync(path)
+            return true
+        } catch {
+            return false
+        }
+    }
+
+    /*
+     * Ensures that a directory exists synchronously.
+     * If the directory does not exist, it will be created recursively.
+     *
+     * @param fs - The file system object.
+     * @param path - The path of the directory to ensure.
+     */
+    export function ensureDirSync(fs: FileSystem, path: string) {
+        if (!existsSync(fs, path)) {
+            fs.mkdirSync(path, { recursive: true })
+        }
+    }
+
+    /**
+     * Provides an implementation of a write stream for FileSystems that don't
+     * have one natively. Buffers all chunks in memory until finalized.
+     */
+    export function createWriteStream(fs: FileSystem, path: string): Writable {
+        if ('createWriteStream' in fs && typeof fs.createWriteStream === 'function') {
+            return fs.createWriteStream(path)
+        }
+
+        const stream = new Writable()
+
+        // who needs streams when you have infinite memory?
+        const buffer: Uint8Array[] = []
+        stream._write = (chunk, _encoding, callback) => {
+            buffer.push(chunk)
+            callback()
+        }
+
+        stream._writev = (chunks, callback) => {
+            for (const { chunk, encoding } of chunks) {
+                stream._write(chunk, encoding, noop)
+            }
+            callback()
+        }
+
+        stream._final = (callback) => {
+            const totalSize = buffer.reduce((result, array) => result + array.length, 0)
+            const merged = new Uint8Array(totalSize)
+            let offset = 0
+            buffer.forEach((array) => {
+                merged.set(array, offset)
+                offset += array.length
+            })
+
+            fs.writeFileSync(path, Buffer.from(merged.buffer))
+            buffer.length = 0
+            callback()
+        }
+
+        return stream
+    }
+
+    /**
+     * Provides an implementation of a read stream for FileSystems that don't
+     * have one natively. Reads the entire content as a single chunk.
+     */
+    export function createReadStream(fs: FileSystem, path: string): Readable {
+        if ('createReadStream' in fs && typeof fs.createReadStream === 'function') {
+            return fs.createReadStream(path)
+        }
+
+        const stream = new Readable()
+
+        stream._read = () => {
+            stream.push(fs.readFileSync(path))
+            stream.push(null)
+        }
+
+        return stream
+    }
+
+    export function traverseDirectory(
+        fs: FileSystem,
+        dir: string,
+        options: {
+            extensions?: string[]
+            ignore_extensions?: string[] | undefined
+            visitor: (filePath: string) => void
+        }
+    ) {
+        if (!FileSystem.existsSync(fs, dir)) {
+            return
+        }
+
+        const files = fs.readdirSync(dir, { withFileTypes: true })
+        const { extensions, ignore_extensions, visitor } = options || {}
+
+        for (const file of files) {
+            const filePath = path.resolve(dir, file.name)
+            if (file.isDirectory()) {
+                traverseDirectory(fs, filePath, options)
+            } else if (
+                ignore_extensions &&
+                ignore_extensions.find((e) => filePath.toLocaleLowerCase().endsWith(e.toLocaleLowerCase()))
+            ) {
+                //skip
+            } else if (
+                !extensions ||
+                extensions.length === 0 ||
+                extensions.some((e) => filePath.toLocaleLowerCase().endsWith(e.toLocaleLowerCase()))
+            ) {
+                visitor(filePath)
+            }
+        }
+    }
+}
+
+export class TsMorphFileSystemWrapper implements ts.FileSystemHost {
+    static ENOENT = 'ENOENT'
+
+    constructor(private readonly fs: FileSystem) {}
+
+    deleteSync(path: string): void {
+        try {
+            this.fs.rmSync(path, { recursive: true })
+        } catch (err) {
+            // It is required to throw this specific subclass of error in order for ts-morph to work properly
+            throw this.#getFileNotFoundErrorIfNecessary(err, path)
+        }
+    }
+
+    readFileSync(path: string, encoding: FileSystem.Encoding = 'utf-8'): string {
+        try {
+            return this.fs.readFileSync(path, { encoding })
+        } catch (err) {
+            // It is required to throw this specific subclass of error in order for ts-morph to work properly
+            throw this.#getFileNotFoundErrorIfNecessary(err, path)
+        }
+    }
+
+    writeFileSync(path: string, text: string): void {
+        this.fs.writeFileSync(path, text)
+    }
+
+    mkdirSync(path: string): void {
+        this.fs.mkdirSync(path, { recursive: true })
+    }
+
+    moveSync(srcPath: string, destPath: string): void {
+        this.fs.renameSync(srcPath, destPath)
+    }
+
+    copySync(srcPath: string, destPath: string): void {
+        this.fs.copyFileSync(srcPath, destPath)
+    }
+
+    fileExistsSync(path: string): boolean {
+        return FileSystem.existsSync(this.fs, path)
+    }
+
+    directoryExistsSync(path: string): boolean {
+        return this.fileExistsSync(path)
+    }
+
+    readDirSync(dir: string): ts.RuntimeDirEntry[] {
+        try {
+            const entries = this.fs.readdirSync(dir, { withFileTypes: true }).map((entry) => {
+                return {
+                    name: entry.name,
+                    isFile: entry.isFile(),
+                    isDirectory: entry.isDirectory(),
+                    isSymlink: entry.isSymbolicLink(),
+                }
+            })
+
+            for (const entry of entries) {
+                entry.name = path.join(dir, entry.name)
+                if (entry.isSymlink) {
+                    try {
+                        const info = this.fs.statSync(entry.name)
+                        if (info != null) {
+                            entry.isDirectory = info.isDirectory()
+                            entry.isFile = info.isFile()
+                        }
+                    } catch {
+                        // Ignore
+                    }
+                }
+            }
+
+            return entries
+        } catch (err) {
+            // It is required to throw this specific subclass of error in order for ts-morph to work properly
+            throw this.#getDirectoryNotFoundErrorIfNecessary(err, dir)
+        }
+    }
+
+    globSync(patterns: string[], opts?: fg.Options): string[] {
+        return fg.sync(
+            patterns.map((pattern) => (this.fileExistsSync(pattern) ? fg.convertPathToPattern(pattern) : pattern)),
+            {
+                absolute: true,
+                cwd: this.getCurrentDirectory(),
+                ...opts,
+                fs: {
+                    readdir: this.fs.readdirSync.bind(this.fs),
+                    readdirSync: this.fs.readdirSync.bind(this.fs),
+                    stat: this.fs.statSync.bind(this.fs),
+                    statSync: this.fs.statSync.bind(this.fs),
+                    lstat: this.fs.lstatSync.bind(this.fs),
+                    lstatSync: this.fs.lstatSync.bind(this.fs),
+                } as unknown as fg.FileSystemAdapter, // TODO: There are probably some compatibility issues here that will cause subtle bugs
+            }
+        )
+    }
+
+    realpathSync(path: string): string {
+        return this.fs.realpathSync(path)
+    }
+
+    getCurrentDirectory(): string {
+        return path.resolve()
+    }
+
+    isCaseSensitive(): boolean {
+        return false // TODO: Should we try to do something more sophisticated here?
+    }
+
+    async delete(path: string): Promise<void> {
+        this.deleteSync(path)
+    }
+
+    async readFile(path: string, encoding?: FileSystem.Encoding): Promise<string> {
+        return this.readFileSync(path, encoding)
+    }
+
+    async writeFile(path: string, text: string): Promise<void> {
+        this.writeFileSync(path, text)
+    }
+
+    async mkdir(path: string): Promise<void> {
+        this.mkdirSync(path)
+    }
+
+    async move(srcPath: string, destPath: string): Promise<void> {
+        this.moveSync(srcPath, destPath)
+    }
+
+    async copy(srcPath: string, destPath: string): Promise<void> {
+        this.copySync(srcPath, destPath)
+    }
+
+    async fileExists(path: string): Promise<boolean> {
+        return this.fileExistsSync(path)
+    }
+
+    async directoryExists(path: string): Promise<boolean> {
+        return this.directoryExistsSync(path)
+    }
+
+    async glob(patterns: string[]): Promise<string[]> {
+        return this.globSync(patterns)
+    }
+
+    /**
+     * Returns a specific subclass of error when a directory is not found which is
+     * required for ts-morph to work properly.
+     */
+    #getDirectoryNotFoundErrorIfNecessary(err: any, path: string) {
+        return this.#isNotExistsError(err) ? new ts.DirectoryNotFoundError(path) : err
+    }
+
+    /**
+     * Returns a specific subclass of error when a file is not found which is required
+     * for ts-morph to work properly.
+     */
+    #getFileNotFoundErrorIfNecessary(err: any, path: string) {
+        return this.#isNotExistsError(err) ? new ts.FileNotFoundError(path) : err
+    }
+
+    /**
+     * Checks if the error is a "not exists" error. This is copied directly from one
+     * of ts-morph's internal `FileSystemHost` implementations.
+     */
+    #isNotExistsError(err: any) {
+        return (
+            (err != null && err.code === TsMorphFileSystemWrapper.ENOENT) ||
+            (err != null && err?.constructor?.name === 'NotFound')
+        )
+    }
+}

package/src/{GUID.ts → guid.ts}

@@ -1,4 +1,4 @@
-import { crypto } from '@servicenow/sdk-project'
+import { crypto } from './crypto'
 
 export function GUID() {
     return crypto.randomUUID().replaceAll('-', '')
@@ -7,10 +7,6 @@ export function GUID() {
 // Matches a hex string exactly 32 characters long
 const snIDRegex = /^[a-f0-9]{32}$/i
 
-export function isGUID(guid: string | number): guid is string {
-    if (typeof guid !== 'string') {
-        return false
-    }
-
+export function isGUID(guid: string): boolean {
     return snIDRegex.test(guid)
 }

package/src/index.ts

@@ -1,7 +1,21 @@
 export * from './util'
-export * from './TypeScript'
-export * from './XML'
+export * from './xml'
 export * from './plugins'
-export * from './GUID'
-export * from './Keys'
-export * from './IncludePaths'
+export * from './guid'
+export * from './keys-registry'
+export * from './fluent-diagnostic'
+export * from './fluent-directive'
+export * from './fluent-file'
+export * from './now-config'
+export * from './compiler'
+export * from './diagnostic'
+export * from './app'
+export * from './json'
+export * from './logger'
+export * from './fs'
+export * from './path'
+export * from './typescript'
+export * from './crypto'
+export * from './compression'
+export * from './formatter'
+export * from './telemetry'

package/src/json.ts

@@ -0,0 +1,20 @@
+import { path as pathModule } from './path'
+import type { FileSystem } from './fs'
+import { Compiler } from './compiler'
+
+import * as JSON5 from 'json5'
+export { JSON5 }
+
+export function readJson(path: string, filename: string, fsOrCompiler: FileSystem | Compiler) {
+    const filePath = pathModule.resolve(path, filename)
+
+    try {
+        return JSON5.parse(
+            fsOrCompiler instanceof Compiler
+                ? fsOrCompiler.getSourceFileOrThrow(filePath).getFullText()
+                : fsOrCompiler.readFileSync(filePath, { encoding: 'utf-8' })
+        )
+    } catch (e) {
+        throw new Error(`Failed to parse JSON file: ${filePath} (Reason: ${e instanceof Error ? e.message : e})`)
+    }
+}