@servicenow/sdk-build-core 3.0.3 → 4.0.0

package/src/compiler.ts

@@ -0,0 +1,384 @@
+import { path } from './path'
+import { isSupportedNode, type SupportedNode, ts } from './typescript'
+import { Diagnostic } from './diagnostic'
+import { FileSystem, TsMorphFileSystemWrapper } from './fs'
+import { NOW_FILE_EXTENSION } from './fluent-file'
+import type { Diagnostics } from './plugins/context'
+
+export type CompilerOptions = ts.CompilerOptions
+export const DEFAULT_COMPILER_OPTIONS: CompilerOptions = {
+    noEmit: true,
+    lib: ['lib.es5.d.ts'],
+    target: ts.ScriptTarget.ES2023,
+    module: ts.ModuleKind.NodeNext,
+    esModuleInterop: true,
+    isolatedModules: true,
+    allowJs: true,
+    checkJs: false,
+    strict: true,
+    alwaysStrict: true,
+    exactOptionalPropertyTypes: true,
+    noEmitOnError: true,
+    noFallthroughCasesInSwitch: true,
+    noImplicitOverride: true,
+    noImplicitReturns: true,
+    noImplicitThis: true,
+    noImplicitAny: false,
+    noUncheckedIndexedAccess: true,
+    noUnusedLocals: true,
+    noUnusedParameters: true,
+    noPropertyAccessFromIndexSignature: true,
+    forceConsistentCasingInFileNames: true,
+    resolveJsonModule: true,
+    skipLibCheck: true,
+    skipDefaultLibCheck: true,
+    allowImportingTsExtensions: true,
+}
+
+const SUPPORTED_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.cts', '.cjs', '.mts', '.mjs', '.json']
+const UNSUPPORTED_EXTENSIONS = ['.test.ts', '.test.js', '.d.ts']
+
+export class Compiler extends ts.Project {
+    private readonly rootDir: string
+    private readonly sourceFileToRelativeModuleSpecifier: Record<string, string> = {}
+    private readonly generatedTableFilePath: string
+    private moduleProject: ts.Project | undefined
+
+    constructor(
+        private readonly fs: FileSystem,
+        {
+            rootDir = '/',
+            sourceFilePaths = [],
+            compilerOptions = DEFAULT_COMPILER_OPTIONS,
+        }: {
+            rootDir?: string
+            sourceFilePaths?: string[]
+            compilerOptions?: CompilerOptions
+        } = {}
+    ) {
+        super({
+            compilerOptions,
+            fileSystem: new TsMorphFileSystemWrapper(fs),
+        })
+
+        this.rootDir = rootDir
+        this.generatedTableFilePath = path.join(this.rootDir, '$$GENERATED$$_common_table.ts')
+        this.addGlobalTableDefinitionFile()
+        // TODO: move this somewhere better, it doesn't work when I put the file contents in packages/core/src/global
+        this.addGlobalModuleExtensions()
+        this.addFluentSourceFilesAtPaths(sourceFilePaths)
+    }
+
+    addGlobalTableDefinitionFile() {
+        const globalTableDefinitionContent = `
+import '@servicenow/sdk/global'
+import { Table } from '@servicenow/sdk/core'
+
+declare global {
+    namespace Now {
+        namespace Internal {
+            namespace TableSchemas {
+            }
+
+            interface Tables {
+            }
+        }
+    }
+}
+`
+        this.createSourceFile(this.generatedTableFilePath, globalTableDefinitionContent, {
+            overwrite: true,
+            scriptKind: ts.ScriptKind.TS,
+        })
+    }
+
+    addGlobalModuleExtensions() {
+        const globalModuleDefinition = `
+declare module '*.html' {
+    const content: string;
+    export default content;
+}`
+
+        this.createSourceFile(path.join(this.rootDir, '$$GENERATED$$_module_extensions.ts'), globalModuleDefinition, {
+            overwrite: true,
+            scriptKind: ts.ScriptKind.TS,
+        })
+    }
+
+    /**
+     * Recursively adds any source files in the specified directory, and returns the added
+     * files. Glob patterns can be supplied to control which files are added. This will also
+     * resolve the dependencies of the added files. If the directory does not exist, an empty
+     * array will be returned.
+     */
+    addSourceFilesFromDirectory(
+        dir: string,
+        extensions: string[] = SUPPORTED_EXTENSIONS,
+        ignore_extensions: string[] = UNSUPPORTED_EXTENSIONS
+    ): ts.SourceFile[] {
+        const files = [] as ts.SourceFile[]
+
+        // Using the filesystem API directly instead of using ts-morph's directory APIs is a
+        // workaround for this issue: https://github.com/dsherret/ts-morph/issues/1554
+        FileSystem.traverseDirectory(this.fs, dir, {
+            extensions,
+            ignore_extensions,
+            visitor: (filePath: string) => {
+                files.push(this.addSourceFileAtPath(filePath))
+            },
+        })
+
+        return files
+    }
+
+    /**
+     * Recursively adds any .now.ts files in the specified directory, and returns the added
+     * files. Glob patterns can be supplied to control which files are added. This will also
+     * resolve the dependencies of the added files. If the directory does not exist, an empty
+     * array will be returned.
+     */
+    addFluentSourceFilesFromDirectory(dir: string): ts.SourceFile[] {
+        return this.addSourceFilesFromDirectory(dir, [NOW_FILE_EXTENSION])
+    }
+
+    addFluentSourceFilesAtPaths(paths: string[]): ts.SourceFile[] {
+        return this.addSourceFilesAtPaths(paths).filter((file) => file.getBaseName().endsWith(NOW_FILE_EXTENSION))
+    }
+
+    getFluentSourceFilesFromDirectory(dir: string) {
+        const directory = this.getDirectoryOrThrow(dir)
+        return directory.getDescendantSourceFiles().filter((file) => file.getBaseName().endsWith(NOW_FILE_EXTENSION))
+    }
+
+    getDiagnosticsForFluentFile(fileOrPath: string | ts.SourceFile): TypeScriptDiagnostic[] {
+        const file = fileOrPath instanceof ts.SourceFile ? fileOrPath : this.getSourceFileOrThrow(fileOrPath)
+        if (!file.getFilePath().endsWith(NOW_FILE_EXTENSION)) {
+            return []
+        }
+        return file
+            .getPreEmitDiagnostics()
+            .map((diagnostic) => {
+                try {
+                    return new TypeScriptDiagnostic(diagnostic)
+                } catch (e) {
+                    return undefined
+                }
+            })
+            .filter((d) => d) as TypeScriptDiagnostic[]
+    }
+
+    getOrCreateSourceFile(path: string, options?: ts.SourceFileCreateOptions): ts.SourceFile {
+        return this.getSourceFile(path) ?? this.createSourceFile(path, '', options)
+    }
+
+    async visitSupportedNodes(
+        node: ts.Node,
+        visitor: (node: SupportedNode) => void | Promise<void>,
+        unsupportedNodeVisitor?: (node: ts.Node) => void | Promise<void>
+    ): Promise<void> {
+        if (node.wasForgotten()) {
+            return
+        }
+
+        if (!isSupportedNode(node)) {
+            await unsupportedNodeVisitor?.(node)
+            return
+        }
+
+        // Surprisingly, forEachChild() is not the same as getChildren().forEach() so we need to
+        // collect all the children using forEachChild() and then iterate
+        const children: ts.Node[] = []
+        node.forEachChild((child) => {
+            children.push(child)
+        })
+
+        for (const child of children) {
+            await this.visitSupportedNodes(child, visitor, unsupportedNodeVisitor)
+        }
+
+        await visitor(node)
+    }
+
+    private getTableSchemaModule(sourceFile: ts.SourceFile) {
+        return sourceFile?.getModule('global')?.getModule('Now')?.getModule('Internal')?.getModule('TableSchemas')
+    }
+
+    private getTableInterface(sourceFile: ts.SourceFile) {
+        return sourceFile?.getModule('global')?.getModule('Now')?.getModule('Internal')?.getInterface('Tables')
+    }
+
+    interfaceExistsInGlobalDeclaration(tableName: string) {
+        const generatedTableFile = this.getSourceFile(this.generatedTableFilePath)
+        const tableSchema = this.getTableSchemaModule(generatedTableFile!)
+        return tableSchema?.getInterfaces().find((value) => value.getName() === tableName)
+    }
+
+    propertyExistsInGlobalDeclaration(tableName: string) {
+        const generatedTableFile = this.getSourceFile(this.generatedTableFilePath)
+        const tableInterface = this.getTableInterface(generatedTableFile!)
+        return tableInterface?.getProperties().find((value) => value.getName() === tableName)
+    }
+
+    importExistsInGlobalDeclaration(resolvedModuleSpecifier: string) {
+        const generatedTableFile = this.getSourceFile(this.generatedTableFilePath)
+        return generatedTableFile
+            ?.getImportDeclarations()
+            .find((value) => value.getModuleSpecifierValue() === resolvedModuleSpecifier)
+    }
+
+    getGeneratedTableFile() {
+        return this.getSourceFile(this.generatedTableFilePath)
+    }
+
+    addTableInterfacesToGlobalDeclaration(data: { interfaces; properties; imports; namedImports }) {
+        const { interfaces, properties, imports, namedImports } = data
+
+        const generatedTableFile = this.getSourceFile(this.generatedTableFilePath)
+        const tableSchema = this.getTableSchemaModule(generatedTableFile!)
+        const tableInterface = this.getTableInterface(generatedTableFile!)
+
+        tableSchema?.addInterfaces(interfaces)
+        tableInterface?.addProperties(properties)
+        generatedTableFile?.addImportDeclarations(Object.values(imports))
+
+        namedImports.forEach((i) => {
+            i.existingImport.addNamedImport({
+                name: i.name,
+            })
+        })
+
+        Object.keys(imports).forEach((filePath) => {
+            this.sourceFileToRelativeModuleSpecifier[filePath] = imports[filePath].moduleSpecifier
+        })
+    }
+
+    removeTableInterfaceFromGlobalDeclaration(sourceFile: string | ts.SourceFile) {
+        const filePath = sourceFile instanceof ts.SourceFile ? sourceFile.getFilePath() : sourceFile
+        const generatedTableFile = this.getSourceFile(this.generatedTableFilePath)
+        const relativeModuleSpecifier = this.sourceFileToRelativeModuleSpecifier[filePath]
+        if (relativeModuleSpecifier) {
+            const foundDecl = generatedTableFile
+                ?.getImportDeclarations()
+                .find((v) => v.getModuleSpecifierValue() === relativeModuleSpecifier)
+            if (foundDecl) {
+                const tables = foundDecl.getNamedImports().map((v) => v.getName())
+                const tableSchema = this.getTableSchemaModule(generatedTableFile!)
+                const tableInterface = this.getTableInterface(generatedTableFile!)
+                tables.forEach((table) => {
+                    tableSchema?.getInterface(table)?.remove()
+                    tableInterface?.getProperty(table)?.remove()
+                })
+                foundDecl.remove()
+            }
+        }
+    }
+
+    isGeneratedTableFile(sourceFile: string | ts.SourceFile): boolean {
+        const sourcePath = sourceFile instanceof ts.SourceFile ? sourceFile.getFilePath() : sourceFile
+        return this.generatedTableFilePath === sourcePath
+    }
+
+    private createModuleProject(fs: FileSystem, tsConfigPath?: string) {
+        return new ts.Project({
+            fileSystem: new TsMorphFileSystemWrapper(fs),
+            ...(tsConfigPath
+                ? {
+                      tsConfigFilePath: tsConfigPath,
+                      // We always want to emit files even if the user config says not to
+                      compilerOptions: { noEmit: false },
+                  }
+                : {
+                      compilerOptions: {
+                          target: ts.ScriptTarget.ES2022,
+                          module: ts.ModuleKind.ES2022,
+                          moduleResolution: ts.ModuleResolutionKind.Bundler,
+                          allowImportingTsExtensions: true,
+                          declaration: false,
+                          sourceMap: false,
+                          skipDefaultLibCheck: true,
+                          skipLibCheck: true,
+                      },
+                  }),
+        })
+    }
+
+    compileModule(
+        moduleFile: ts.SourceFile,
+        fs: FileSystem,
+        diagnostics: Diagnostics,
+        tsConfigPath?: string
+    ): string | undefined {
+        if (!this.moduleProject) {
+            this.moduleProject = this.createModuleProject(fs, tsConfigPath)
+        }
+        const modulePath = moduleFile.getFilePath()
+        let sourceFile: ts.SourceFile | undefined
+        if (tsConfigPath) {
+            sourceFile = this.moduleProject.getSourceFile(modulePath)
+
+            if (!sourceFile) {
+                diagnostics.error(moduleFile, `${path} not included in project. Check your tsconfig: ${tsConfigPath}`)
+                return undefined
+            }
+        } else {
+            sourceFile = this.moduleProject.createSourceFile(modulePath, moduleFile.getFullText(), {
+                overwrite: true,
+                scriptKind: ts.ScriptKind.TS,
+            })
+        }
+
+        sourceFile.getPreEmitDiagnostics().forEach((diagnostic) => {
+            try {
+                diagnostics.add(new TypeScriptDiagnostic(diagnostic))
+            } catch (e) {
+                //ignore
+            }
+        })
+
+        const emitResult = sourceFile.getEmitOutput()
+        emitResult.getDiagnostics().forEach((d) => {
+            try {
+                const diagnostic = new TypeScriptDiagnostic(d)
+                if (diagnostic.level === Diagnostic.Level.Error) {
+                    diagnostics.add(diagnostic)
+                }
+            } catch (e) {
+                //ignore
+            }
+        })
+
+        const output = emitResult.getOutputFiles()[0]
+        if (!output) {
+            diagnostics.error(moduleFile, `Failed to get emit output for module: ${modulePath}`)
+        }
+
+        return output?.getText()
+    }
+}
+
+export class TypeScriptDiagnostic extends Diagnostic {
+    constructor(private readonly diagnostic: ts.Diagnostic) {
+        const message = diagnostic.getMessageText()
+        const messageText = typeof message === 'string' ? message : message.getMessageText()
+        const start = diagnostic.getStart() ?? 0
+        const end = start + (diagnostic.getLength() ?? 0)
+        const file = diagnostic.getSourceFile()
+
+        if (!file) {
+            throw new Error(`TypeScript diagnostic does not have a source file (Message: ${messageText})`)
+        }
+
+        super(
+            messageText,
+            file,
+            { start, end },
+            diagnostic.getCode(),
+            'ts',
+            Diagnostic.Level.fromCategory(diagnostic.getCategory())
+        )
+    }
+
+    public override asTypeScriptDiagnostic(): ts.ts.Diagnostic {
+        return this.diagnostic.compilerObject
+    }
+}

package/src/compression.ts

@@ -0,0 +1,93 @@
+import { ZipDeflate, unzipSync, Zip, gzipSync } from 'fflate'
+import { FileSystem, TsMorphFileSystemWrapper } from './fs'
+import { path } from './path'
+
+const ZIP_STATUS_FILE = 'status.json'
+
+export const unzipAppPackage = async (
+    fs: FileSystem,
+    zipPath: string,
+    targetPath: string
+): Promise<{ files: string[] }> => {
+    const zipArrBuf = new Uint8Array(fs.readFileSync(zipPath))
+    const unzipResult = unzipSync(zipArrBuf)
+
+    //remove unnecessary package inventory file if present
+    if (unzipResult['package_inventory.csv']) {
+        delete unzipResult['package_inventory.csv']
+    }
+
+    // check the status of download operation
+    if (ZIP_STATUS_FILE in unzipResult) {
+        const response = JSON.parse(Buffer.from(unzipResult[ZIP_STATUS_FILE]).toString('utf8'))
+        if (response.status === 'error') {
+            throw new Error('Application download failed with error, ' + response.message)
+        }
+        delete unzipResult[ZIP_STATUS_FILE]
+    }
+
+    const files = Object.entries(unzipResult).map(([filePath, data]) => {
+        const fullPath = path.join(targetPath, filePath)
+
+        // Create directories if necessary
+        const dir = path.dirname(fullPath)
+        FileSystem.ensureDirSync(fs, dir)
+
+        // Write file content to the filesystem
+        fs.writeFileSync(fullPath, data)
+
+        return fullPath
+    })
+
+    return { files }
+}
+
+export const zipDirectory = async (fs: FileSystem, source: string, destination: string): Promise<string> => {
+    return new Promise<string>((resolve, reject) => {
+        try {
+            const z = new Zip()
+
+            const outputStream = FileSystem.createWriteStream(fs, destination)
+
+            z.ondata = (err, data, final) => {
+                if (err) {
+                    outputStream.destroy()
+                    reject(err)
+                } else {
+                    outputStream.write(data)
+                    if (final) {
+                        outputStream.end()
+                    }
+                }
+            }
+
+            outputStream.on('finish', () => {
+                resolve(destination)
+            })
+
+            outputStream.on('error', (error) => {
+                reject(error)
+            })
+
+            // Using our own glob for browser compatibility
+            const wrappedFs = new TsMorphFileSystemWrapper(fs)
+            const files = wrappedFs.globSync(['**'], {
+                cwd: source,
+            })
+
+            for (const file of files) {
+                const fp = path.normalize(file)
+                const data = fs.readFileSync(fp)
+                const zf = new ZipDeflate(fp.replace(source, ''), { level: 6 })
+                z.add(zf)
+                zf.push(data, true)
+            }
+
+            z.end()
+        } catch (err) {
+            reject(err)
+        }
+    })
+}
+
+export { gzipSync }

package/src/crypto.ts

@@ -0,0 +1,5 @@
+// Node 20+ globally available Crypto Module -OR- Browser Crypto Module
+const globalCrypto = <Crypto>(<any>globalThis.crypto)?.webcrypto || globalThis.crypto
+// Globally available crypto (Node or Browser) -OR- Node Web Crypto (We can get rid of this in April 2025 after Node 18 is EOL)
+// biome-ignore lint/style/noRestrictedImports: This is where we re-export our version of the module
+export const crypto = globalCrypto || require('node:crypto').webcrypto

package/src/diagnostic.ts

@@ -0,0 +1,108 @@
+import * as lsp from 'vscode-languageserver'
+import * as os from 'os'
+import { ts } from './typescript'
+import type { Logger } from './logger'
+
+type PrintOptions = {
+    colors?: boolean
+    noThrow?: boolean
+}
+
+export abstract class Diagnostic {
+    constructor(
+        public readonly message: string,
+        public readonly file: ts.SourceFile,
+        public readonly position: { start: number; end: number },
+        public readonly code: ts.SyntaxKind,
+        public readonly source: 'fluent' | 'ts',
+        public readonly level: Diagnostic.Level = Diagnostic.Level.Error
+    ) {}
+
+    public abstract asTypeScriptDiagnostic(): ts.ts.Diagnostic
+
+    public asLspDiagnostic(): lsp.Diagnostic {
+        const start = this.file.compilerNode.getLineAndCharacterOfPosition(this.position.start)
+        const end = this.file.compilerNode.getLineAndCharacterOfPosition(this.position.end)
+
+        return {
+            message: this.message,
+            range: { start, end },
+            severity: Diagnostic.Level.toSeverity(this.level),
+            code: this.code,
+            source: this.source,
+        }
+    }
+
+    public getFormattedText(colors = true) {
+        const host: ts.ts.FormatDiagnosticsHost = {
+            getCurrentDirectory: () => this.file.getProject().getFileSystem().getCurrentDirectory(),
+            getCanonicalFileName: (fileName) => fileName,
+            getNewLine: () => os.EOL,
+        }
+
+        return colors
+            ? ts.ts.formatDiagnosticsWithColorAndContext([this.asTypeScriptDiagnostic()], host)
+            : ts.ts.formatDiagnostic(this.asTypeScriptDiagnostic(), host)
+    }
+
+    public print(logger: Logger, { noThrow = false, colors = true }: PrintOptions = {}): void {
+        if (this.level === Diagnostic.Level.Error) {
+            const errorMessage = this.getFormattedText(colors)
+            if (noThrow) {
+                logger.error(errorMessage)
+            } else {
+                logger.error('Diagnostic errors found in source files, fix errors and re-run transform/build')
+                throw new Error(errorMessage)
+            }
+        } else if (this.level === Diagnostic.Level.Warn) {
+            logger.warn(this.getFormattedText(colors))
+        }
+    }
+}
+
+export namespace Diagnostic {
+    export enum Level {
+        Error = 1,
+        Warn = 2,
+        Info = 3,
+        Hint = 4,
+    }
+
+    export namespace Level {
+        export function fromCategory(category: ts.DiagnosticCategory): Level {
+            return {
+                [ts.DiagnosticCategory.Error]: Diagnostic.Level.Error,
+                [ts.DiagnosticCategory.Warning]: Diagnostic.Level.Warn,
+                [ts.DiagnosticCategory.Message]: Diagnostic.Level.Info,
+                [ts.DiagnosticCategory.Suggestion]: Diagnostic.Level.Hint,
+            }[category]
+        }
+
+        export function toCategory(level: Level): ts.DiagnosticCategory {
+            return {
+                [Diagnostic.Level.Error]: ts.DiagnosticCategory.Error,
+                [Diagnostic.Level.Warn]: ts.DiagnosticCategory.Warning,
+                [Diagnostic.Level.Info]: ts.DiagnosticCategory.Message,
+                [Diagnostic.Level.Hint]: ts.DiagnosticCategory.Suggestion,
+            }[level]
+        }
+
+        export function fromSeverity(severity: lsp.DiagnosticSeverity): Level {
+            return {
+                [lsp.DiagnosticSeverity.Error]: Diagnostic.Level.Error,
+                [lsp.DiagnosticSeverity.Warning]: Diagnostic.Level.Warn,
+                [lsp.DiagnosticSeverity.Information]: Diagnostic.Level.Info,
+                [lsp.DiagnosticSeverity.Hint]: Diagnostic.Level.Hint,
+            }[severity]
+        }
+
+        export function toSeverity(level: Level): lsp.DiagnosticSeverity {
+            return {
+                [Diagnostic.Level.Error]: lsp.DiagnosticSeverity.Error,
+                [Diagnostic.Level.Warn]: lsp.DiagnosticSeverity.Warning,
+                [Diagnostic.Level.Info]: lsp.DiagnosticSeverity.Information,
+                [Diagnostic.Level.Hint]: lsp.DiagnosticSeverity.Hint,
+            }[level]
+        }
+    }
+}

package/src/{plugins/Diagnostic.ts → fluent-diagnostic.ts}

@@ -1,8 +1,9 @@
-import { Diagnostic, ts, tsc } from '@servicenow/sdk-project'
+import { Diagnostic } from './diagnostic'
+import type { ts, tsc } from './typescript'
 
 export class FluentDiagnostic extends Diagnostic {
     constructor(
-        node: ts.Node,
+        public readonly node: ts.Node,
         message: string,
         { level = Diagnostic.Level.Error, code = node.getKind() }: { level?: Diagnostic.Level; code?: number } = {}
     ) {
@@ -20,11 +21,3 @@ export class FluentDiagnostic extends Diagnostic {
         }
     }
 }
-
-export function findObjectPropertyValue(callExpression: ts.CallExpression, field: string) {
-    const property = callExpression
-        .getFirstDescendantByKind(ts.SyntaxKind.ObjectLiteralExpression)
-        ?.getProperty(field) as ts.PropertyAssignment
-
-    return property?.getInitializer() || callExpression
-}

package/src/fluent-directive.ts

@@ -0,0 +1,63 @@
+import { ts } from './typescript'
+
+type FluentDirective = '@fluent-ignore' | '@fluent-disable-sync' | '@fluent-disable-sync-for-file'
+
+type CacheEntry = Partial<Record<FluentDirective, boolean>>
+const CACHE = new WeakMap<ts.Node, CacheEntry>()
+function cacheGet(node: ts.Node): CacheEntry {
+    return CACHE.get(node) ?? CACHE.set(node, {}).get(node)!
+}
+
+/**
+ * Determines if the specified node or any of its ancestors have the specified directive in
+ * one of their leading comment ranges. Avoids regex for optimal performance.
+ */
+export function hasDirective(node: ts.Node, directive: FluentDirective): boolean {
+    const cache = cacheGet(node)
+    if (cache[directive] !== undefined) {
+        return cache[directive]
+    }
+
+    for (const comment of getComments(node)) {
+        const text = comment.getText()
+        const idx = text.indexOf(directive)
+        if (idx >= 0) {
+            return (cache[directive] =
+                isDirectiveBoundary(text.charCodeAt(idx - 1)) &&
+                isDirectiveBoundary(text.charCodeAt(idx + directive.length)))
+        }
+    }
+
+    const parent = node.getParent()
+    return (cache[directive] = !!parent && hasDirective(parent, directive))
+}
+
+function getComments(node: ts.Node): ts.CommentRange[] | ts.CommentStatement[] {
+    if (!ts.Node.isSourceFile(node)) {
+        return node.getLeadingCommentRanges()
+    }
+
+    const top = node.getFirstChildIfKind(ts.SyntaxKind.SyntaxList)?.getFirstChild()
+    return ts.Node.isCommentStatement(top) ? [top] : []
+}
+
+const DIRECTIVE_CHARS = {
+    '-': (c: number) => c === 45,
+    '@': (c: number) => c === 64,
+    'A-Z': (c: number) => c >= 65 && c <= 90,
+    'a-z': (c: number) => c >= 97 && c <= 122,
+}
+
+function isDirectiveBoundary(code: number): boolean {
+    if (isNaN(code)) {
+        return true
+    }
+
+    for (const test of Object.values(DIRECTIVE_CHARS)) {
+        if (test(code)) {
+            return false
+        }
+    }
+
+    return true
+}

package/src/fluent-file.ts

@@ -0,0 +1,13 @@
+import { ts } from './typescript'
+import type { ProjectFile } from './plugins'
+
+export const NOW_FILE_EXTENSION = '.now.ts'
+
+export function isFluentNode(node: ts.Node): boolean {
+    return isFluentFile(node.getSourceFile())
+}
+
+export function isFluentFile(file: ts.SourceFile | ProjectFile | string): boolean {
+    const path = ts.Node.isNode(file) ? file.getFilePath() : typeof file === 'string' ? file : file.getPath()
+    return path.endsWith(NOW_FILE_EXTENSION)
+}