@servicenow/sdk-build-core 3.0.3 → 4.0.0

package/src/now-config.ts

@@ -0,0 +1,337 @@
+import { parsePackageJson } from './app'
+import * as z from 'zod'
+import { path } from './path'
+import { FileSystem } from './fs'
+import type { Logger } from './logger'
+import { Validator as JsonSchemaValidator, type ValidationError } from 'jsonschema'
+import { readJson } from './json'
+import { Compiler } from './compiler'
+import { GUID } from './guid'
+
+export type NowConfig = z.output<typeof NowConfigSchema>
+export type NowConfigOptions = z.input<typeof NowConfigSchema>
+
+type DeprecatedField = {
+    replacedBy?: string
+    transfer?: boolean
+}
+
+const NowConfigSchema = z
+    .object({
+        scope: z.string(),
+        scopeId: z.string(),
+        name: z.string().optional(),
+        serverModulesDir: z.string().default(path.join('src', 'server')),
+        modulePaths: z.record(z.string(), z.string()).default({}),
+        metadataDir: z.string().default('metadata'),
+        fluentDir: z.string().default(path.join('src', 'fluent')),
+        clientDir: z.string().default(path.join('src', 'client')),
+        typesDir: z.string().default(path.join('@types', 'servicenow')),
+        generatedDir: z.string().default(`generated`),
+        staticContentDir: z.string().default(path.join('dist', 'static')),
+        staticContentPaths: z.record(z.string(), z.string()).default({
+            'src/client/*.html': 'dist/static/*.html',
+        }),
+        appOutputDir: z.string().default(path.join('dist', 'app')),
+        packOutputDir: z.string().default('target'),
+        npmUpdateCheck: z.literal(false).or(z.number()).default(10),
+        dependencies: z
+            .object({
+                applications: z
+                    .record(
+                        z.string(),
+                        z.object({
+                            tables: z.array(z.string()).or(z.literal('*')).optional(),
+                        })
+                    )
+                    .optional(),
+            })
+            .optional(),
+        ignoreTransformTableList: z.array(z.string()).default([]),
+        tsconfigPath: z.string().optional(),
+        scripts: z.record(z.string(), z.string()).default({
+            prebuild: 'now.prebuild.mjs',
+            postbuild: 'now.postbuild.mjs',
+        }),
+        tableOutputFormat: z.enum(['bootstrap', 'component']).default('bootstrap'),
+
+        moduleDir: z.string().optional(), // Deprecated
+        compileOutputDir: z.string().optional(), // Deprecated
+        sourceDir: z.string().optional(), // Deprecated
+        transpiledSourceDir: z.string().optional(), // Deprecated
+
+        // SYS_APP UI values
+        active: z.boolean().optional(),
+        accessControls: z
+            .object({
+                scopedAdministration: z.boolean().optional(),
+                canEditInStudio: z.boolean().optional(),
+                runtimeAccessTracking: z.string().optional(),
+                restrictTableAccess: z.boolean().optional(),
+                userRole: z.string().optional(),
+                private: z.boolean().optional(),
+                trackable: z.boolean().optional(),
+                uninstallBlocked: z.boolean().optional(),
+                hideOnUI: z.boolean().optional(),
+            })
+            .optional(),
+        licensing: z
+            .object({
+                licensable: z.boolean().optional(),
+                enforceLicense: z.string().optional(),
+                licenseModel: z.string().optional(),
+                licenseCategory: z.string().optional(),
+                subscriptionEntitlement: z.string().optional(),
+            })
+            .optional(),
+        jsLevel: z.string().optional(),
+        menu: z.string().optional(),
+        description: z.string().optional(),
+        logo: z.string().optional(),
+        guidedSetupGuid: z.string().optional(),
+        installedAsDependency: z.boolean().optional(),
+    })
+    .refine((data) => {
+        if (!data.generatedDir.startsWith(data.fluentDir)) {
+            data.generatedDir = path.join(data.fluentDir, data.generatedDir)
+        }
+
+        const sdkDirectories: Array<
+            keyof Omit<
+                typeof data,
+                | 'scope'
+                | 'scopeId'
+                | 'npmUpdateCheck'
+                | 'dependencies'
+                | 'ignoreTransformTableList'
+                | 'modulePaths'
+                | 'staticContentPaths'
+                | 'tsconfigPath'
+                | 'active'
+                | 'licensing'
+                | 'accessControls'
+                | 'jsLevel'
+                | 'menu'
+                | 'logo'
+                | 'guidedSetupGuid'
+                | 'description'
+                | 'installedAsDependency'
+                | 'scripts'
+                | 'tableOutputFormat'
+            >
+        > = [
+            'serverModulesDir',
+            'metadataDir',
+            'fluentDir',
+            'clientDir',
+            'generatedDir',
+            'staticContentDir',
+            'appOutputDir',
+            'sourceDir',
+            'transpiledSourceDir',
+            'packOutputDir',
+            'moduleDir',
+            'compileOutputDir',
+        ]
+
+        sdkDirectories.forEach((dir) => {
+            if (data[dir]) {
+                data[dir] = path.normalize(data[dir])
+            }
+        })
+
+        return data
+    })
+
+export namespace NowConfig {
+    export const FILE_NAME = 'now.config.json'
+
+    export const ERROR_ON_DEPRECATED_PROPS = {
+        transpiledSourceDir: `NowConfig: 'modulePaths' replaces 'transpiledSourceDir', please remove 'transpiledSourceDir'
+        and map original source files to transpiled output using 'modulePaths'
+    
+        Ex:
+          "modulePaths": {
+              "src/server/*.js": "dist/modules/*.js",
+              "src/server/*.ts": "dist/modules/*.js",
+          }
+    
+        If you are not intending to do custom module transpilation, please remove 'transpiledSourceDir'
+        and ensure 'serverModulesDir' is set to the directory containing modules `,
+    }
+
+    /**
+     *
+     * @param config Configuration Records read from now.config.json
+     * @param rootDir Root project directory used to parse tsconfig from tsconfigPath
+     * @param fs FileSystem
+     * @param logger
+     * @returns zod parsed NowConfig
+     */
+    export const parse = (config: Record<string, unknown>, logger: Logger): NowConfig => {
+        checkRemovedProperties(config)
+        replaceDeprecatedFields(config, logger)
+        return getParsedNowConfigData(config)
+    }
+
+    export const parseFromPath = (path: string, fsOrCompiler: FileSystem | Compiler, logger: Logger): NowConfig => {
+        const nowConfig = readNowConfigJsonFile(path, fsOrCompiler)
+        if (!nowConfig) {
+            throw new Error(`Failed to parse config file at path ${path}`)
+        }
+
+        return parse(nowConfig, logger)
+    }
+
+    export const parseFromDirectory = (dir: string, fs: FileSystem, logger: Logger): NowConfig => {
+        return parse(readNowConfigJsonFile(getFilePath(dir), fs) ?? parsePackageJson(dir, fs)['now'] ?? {}, logger)
+    }
+
+    export const exists = (dir: string, fs: FileSystem): boolean => {
+        if (FileSystem.existsSync(fs, getFilePath(dir))) {
+            return true
+        } else if (FileSystem.existsSync(fs, path.join(dir, 'package.json')) && parsePackageJson(dir, fs)['now']) {
+            return true
+        }
+        return false
+    }
+
+    export const getFilePath = (rootDir: string): string => {
+        return path.join(rootDir, FILE_NAME)
+    }
+
+    export function create({ scope, scopeId, ...rest }: Partial<NowConfigOptions> = {}): NowConfig {
+        return NowConfigSchema.parse({
+            scope: scope ?? 'global',
+            scopeId: scopeId ?? GUID(),
+            ...rest,
+        })
+    }
+
+    export function load({
+        rootDir,
+        compiler,
+        fileSystem,
+        logger,
+    }: {
+        rootDir: string
+        compiler: Compiler
+        fileSystem: FileSystem
+        logger: Logger
+    }): NowConfig {
+        const configFilePath = getFilePath(rootDir)
+        if (compiler.getSourceFile(configFilePath)) {
+            return NowConfig.parseFromPath(configFilePath, compiler, logger)
+        }
+
+        if (exists(rootDir, fileSystem)) {
+            return NowConfig.parseFromPath(configFilePath, fileSystem, logger)
+        }
+
+        return NowConfig.create()
+    }
+}
+
+const NOW_CONFIG_SCHEMA = require('../now.config.schema.json')
+
+function getNowConfigFileValidationResults(json: unknown) {
+    const validator = new JsonSchemaValidator()
+    return validator.validate(json, NOW_CONFIG_SCHEMA)
+}
+
+function getParsedNowConfigData(config: Record<string, unknown>): NowConfig {
+    const parsedNowConfig = NowConfigSchema.safeParse(config)
+    if (!parsedNowConfig.success) {
+        let errMsg = `Invalid '${NowConfig.FILE_NAME}' file:\n`
+        parsedNowConfig.error.errors.map((err) => (errMsg += `${err.path}: ${err.message}\n`))
+        throw new Error(errMsg)
+    }
+
+    return parsedNowConfig.data
+}
+
+function validateNowConfigJsonFile(filePath: string, fsOrCompiler: FileSystem | Compiler) {
+    const json: unknown = readJson(filePath, '', fsOrCompiler)
+    if (!isObjectWithStringKeys(json)) {
+        throw new Error(`Config file '${NowConfig.FILE_NAME}' is empty or malformed`)
+    }
+
+    const result = getNowConfigFileValidationResults(json)
+    if (result.errors.length > 0) {
+        throw new Error(`${NowConfig.FILE_NAME} - error: ${formatValidationErrorMessage(result.errors)}`)
+    }
+
+    return json
+}
+
+function formatValidationErrorMessage(errors: ValidationError[]) {
+    return errors
+        .map((e) => {
+            if (!e.path.length) {
+                if (e.message === 'is of prohibited type [object Object]') {
+                    return e.argument.message
+                }
+                return e.message
+            }
+
+            return `"${e.path.join('.')}" ${e.message}`
+        })
+        .join(', ')
+}
+
+function readNowConfigJsonFile(filePath: string, fsOrCompiler: FileSystem | Compiler) {
+    const exists =
+        fsOrCompiler instanceof Compiler
+            ? !!fsOrCompiler.getSourceFile(filePath)
+            : FileSystem.existsSync(fsOrCompiler, filePath)
+
+    if (exists) {
+        return validateNowConfigJsonFile(filePath, fsOrCompiler)
+    }
+
+    return null
+}
+
+function isObjectWithStringKeys(obj: unknown): obj is Record<string, unknown> {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+        return false
+    }
+
+    for (const key in obj) {
+        if (typeof key !== 'string') {
+            return false
+        }
+    }
+
+    return true
+}
+
+const DEPRECATED_FIELDS: Record<string, DeprecatedField> = {
+    moduleDir: { replacedBy: 'serverModulesDir', transfer: true },
+    compileOutputDir: { replacedBy: 'appOutputDir', transfer: true },
+    entitiesDir: { replacedBy: 'fluentDir', transfer: true },
+    transpiledSourceDir: { replacedBy: 'modulePaths' },
+    sourceDir: {},
+}
+
+function replaceDeprecatedFields(config: Record<string, unknown>, logger: Logger) {
+    for (const [name, { replacedBy, transfer }] of Object.entries(DEPRECATED_FIELDS)) {
+        if (name in config) {
+            logger.warn(
+                `'${name}' is deprecated${replacedBy ? `, please replace with '${replacedBy}'` : ' and can be removed'}`
+            )
+
+            if (transfer && replacedBy) {
+                config[replacedBy] = config[name]
+            }
+        }
+    }
+}
+
+function checkRemovedProperties(config: Record<string, any>): void {
+    for (const [property, message] of Object.entries(NowConfig.ERROR_ON_DEPRECATED_PROPS)) {
+        if (property in config) {
+            throw new Error(message)
+        }
+    }
+}

package/src/path.ts

@@ -0,0 +1,9 @@
+import pathe from 'pathe'
+
+export type PosixPathModule = Omit<typeof pathe, 'toNamespacedPath'>
+
+const { toNamespacedPath, ...rest } = pathe
+
+export const path: PosixPathModule = {
+    ...rest,
+}

package/src/plugins/cache.ts

@@ -0,0 +1,45 @@
+class SuccessEntry<T = unknown> {
+    constructor(private readonly value: T) {}
+
+    unwrap(): T {
+        return this.value
+    }
+
+    isError(): this is ErrorEntry {
+        return false
+    }
+}
+
+class ErrorEntry {
+    constructor(private readonly error: unknown) {}
+
+    unwrap(): unknown {
+        return this.error
+    }
+
+    isError(): this is ErrorEntry {
+        return true
+    }
+}
+
+export class Cache<K extends object, V> {
+    private cache = new WeakMap()
+
+    get(key: K): SuccessEntry<V> | ErrorEntry | undefined {
+        return this.cache.get(key)
+    }
+
+    put<const T extends V>(key: K, value: T): T {
+        this.cache.set(key, new SuccessEntry(value))
+        return value
+    }
+
+    error<const T>(key: K, error: T): T {
+        this.cache.set(key, new ErrorEntry(error))
+        return error
+    }
+
+    clear(): void {
+        this.cache = new WeakMap()
+    }
+}

package/src/plugins/context.ts

@@ -0,0 +1,93 @@
+import type { Compiler } from '../compiler'
+import type { Diagnostic } from '../diagnostic'
+import type { FileSystem } from '../fs'
+import type { Logger } from '../logger'
+import type { Package } from '../app'
+import type { ts } from '../typescript'
+import type { Plugin, Plugins, Result } from './plugin'
+import type { Product, Source } from './product'
+import type { Project } from './project'
+import type { Action, CoalesceKeys, ObjectShape, Record, RecordId, Shape, StringShape } from './shape'
+import type { File, InstallCategory } from './file'
+import type { Formatter } from '../formatter'
+import type { NowConfig } from '../now-config'
+import type { Database } from './database'
+
+export interface Keys {
+    queryExplicitId(table: string, key: string | number | Shape): string | undefined
+    registerExplicitId(table: string, key: string | number | Shape, guidOverride?: string): string
+    deleteExplicitId(table: string, key: string | number, guidOverride?: string): string
+    queryCoalesceId(table: string, key: CoalesceKeys): string | undefined
+    registerCoalesceId(table: string, key: CoalesceKeys, guidOverride?: string): string
+    deleteCoalesceId(table: string, key: CoalesceKeys, guidOverride?: string): string
+    getEffectiveDeletedKeys(): Now.Internal.AnyKey[]
+    getSourceFile(): ts.SourceFile
+    getFilePath(): string
+    getValue(): Now.Internal.KeysRegistry
+    commit(formatter?: Formatter): Promise<void>
+    reload(): void
+}
+
+export interface Diagnostics {
+    error(source: Product | ts.Node, message: string): void
+    warn(source: Product | ts.Node, message: string): void
+    info(source: Product | ts.Node, message: string): void
+    hint(source: Product | ts.Node, message: string): void
+    add(diagnostic: Diagnostic): void
+    getAll(file?: string): Diagnostic[]
+    clear(file?: string): void
+    getWarnings(file?: string): Diagnostic[]
+    hasErrors(file?: string): boolean
+    getErrors(file?: string): Diagnostic[]
+}
+
+export interface Transform {
+    toShape(node: ts.Node, ...plugins: Plugin[]): Promise<Result<Shape>>
+    recordToShape(record: Record, database: Database, ...plugins: Plugin[]): Promise<Result<Shape>>
+    toSubclass<const S extends Shape>(shape: S, ...plugins: Plugin[]): Result<S>
+    toRecord(node: ts.Node, ...plugins: Plugin[]): Promise<Result<Record>>
+    toRecord(shape: Shape, ...plugins: Plugin[]): Promise<Result<Record>>
+    toRecord(file: File, ...plugins: Plugin[]): Promise<Result<Record>>
+    toRecord(source: ts.Node | Shape | File, ...plugins: Plugin[]): Promise<Result<Record>>
+}
+
+export interface Factory {
+    createShape<const S extends Shape>(shape: S): S
+
+    createRecord(args: {
+        source: Source
+        table: string
+        explicitId?: string | Shape
+        guidOverride?: string
+        properties: NonNullable<object>
+        action?: Action
+        installCategory?: InstallCategory
+    }): Record
+
+    createReference(args: {
+        source: Source
+        table: string | StringShape
+        guid?: string | StringShape | undefined
+        keys?: globalThis.Record<string, string | Shape> | ObjectShape | undefined
+    }): RecordId
+}
+
+export interface Parser {
+    parsePayload(file: File): Record[]
+}
+
+export type Context = {
+    readonly self: Plugin
+    readonly fs: FileSystem
+    readonly logger: Logger
+    readonly packageJson: Package
+    readonly config: NowConfig
+    readonly project: Project
+    readonly compiler: Compiler
+    readonly plugins: Plugins
+    readonly keys: Keys
+    readonly diagnostics: Diagnostics
+    readonly transform: Transform
+    readonly factory: Factory
+    readonly parser: Parser
+}

package/src/plugins/database.ts

@@ -0,0 +1,121 @@
+import type { Record, RecordId } from './shape'
+
+type Query = { [column: string]: unknown }
+
+export class Database implements Iterable<Record> {
+    private readonly database: { [table: string]: { [guid: string]: Record } } = {}
+
+    constructor(records: Record[] = []) {
+        this.insert(...records)
+    }
+
+    insert(...records: Record[]): void {
+        for (const record of records) {
+            const table = (this.database[record.getTable()] ??= {})
+            const guid = record.getId().getValue()
+            table[guid] = record
+        }
+    }
+
+    resolve(id: RecordId): Record | undefined {
+        const table = id.getTable()
+        const guid = id.getValue()
+
+        const record = this.database[table]?.[guid]
+        if (record) {
+            return record
+        }
+
+        const keys = id.getKeys()
+        if (!keys) {
+            return undefined
+        }
+
+        const matches = this.query(table, keys)
+        if (matches.length > 1) {
+            throw new Error(`Multiple records found for table "${table}" with coalesce keys: ${JSON.stringify(keys)}`)
+        }
+
+        return matches[0]
+    }
+    get(table: string, guid: string): Record | undefined
+    get(table: string, query: Query): Record | undefined
+    get(table: string, guidOrQuery: string | Query): Record | undefined {
+        if (typeof guidOrQuery === 'string') {
+            return this.database[table]?.[guidOrQuery]
+        }
+
+        const [record, ...rest] = this.query(table, guidOrQuery)
+        if (rest.length > 0) {
+            throw new Error(`Expected get() to return no more than 1 match, but ${rest.length + 1} matches were found.`)
+        }
+
+        return record
+    }
+
+    query(table?: string, query: Query = {}): Record[] {
+        if (!table) {
+            return Object.values(this.database).flatMap((table) => Object.values(table))
+        }
+
+        const records: Record[] = []
+        outer: for (const record of Object.values(this.database[table] ?? {})) {
+            for (const [column, value] of Object.entries(query)) {
+                if (!record.get(column).equals(value)) {
+                    continue outer
+                }
+            }
+
+            records.push(record)
+        }
+
+        return records
+    }
+
+    compare(other: Database | Record[]): DiffDatabase {
+        const diff = new DiffDatabase(this.query())
+        diff.insert(...(other instanceof Database ? other.query() : other))
+        return diff
+    }
+
+    [Symbol.iterator](): IterableIterator<Record> {
+        return this.query()[Symbol.iterator]()
+    }
+}
+
+/**
+ * The initial set of records passed into the constructor is treated as the baseline. Any record
+ * inserted after that will be tracked as "changed" unless it is equal to its baseline counterpart.
+ * Useful for getting a diff/delta between two databases.
+ */
+export class DiffDatabase extends Database {
+    private readonly changedGuids: string[] = []
+
+    constructor(records: Record[] = []) {
+        super(records)
+    }
+
+    override insert(...records: Record[]): void {
+        if (!this.changedGuids) {
+            // This will happen when called from the super constructor
+            super.insert(...records)
+            return
+        }
+
+        for (const record of records) {
+            const id = record.getId()
+            const existing = this.resolve(id)
+            if (existing && !existing.strictEquals(record)) {
+                this.changedGuids.push(id.getValue())
+                super.insert(existing.merge(record))
+            } else if (!existing) {
+                this.changedGuids.push(id.getValue())
+                super.insert(record)
+            }
+        }
+    }
+
+    isChanged(record: Record): boolean {
+        return this.changedGuids.includes(record.getId().getValue())
+    }
+}

package/src/plugins/file.ts

@@ -0,0 +1,19 @@
+export type File = {
+    path: string
+    content: string
+}
+
+export type InstallCategory =
+    | 'dictionary'
+    | 'unload'
+    | 'unload.demo'
+    | 'update'
+    | 'apply_once'
+    | 'scope'
+    | 'author_elective_update'
+
+export type OutputFile = {
+    name: string
+    category: InstallCategory
+    content: string
+}

package/src/plugins/index.ts

@@ -1,5 +1,9 @@
-export { Plugin } from './Plugin'
-export { type Context, type HandledStates, type HandledInfo } from './Context'
-export * from './behaviors'
-export * from './util'
-export * from './Diagnostic'
+export * from './shape'
+export * from './file'
+export * from './context'
+export * from './plugin'
+export * from './product'
+export * from './project'
+export * from './database'
+export * from './time'
+export * from './usage'