@servicenow/sdk-build-core 3.0.3 → 4.0.0

package/src/Keys.ts

@@ -1,274 +0,0 @@
-import { path, ts } from '@servicenow/sdk-project'
-import { parseType } from './TypeScript'
-import { GUID, isGUID } from './GUID'
-import * as z from 'zod'
-import * as _ from 'lodash'
-import { Context } from './plugins'
-
-export const KEYS_MODULE = '@servicenow/sdk/global'
-export const KEYS_FILE_NAME = 'keys.ts'
-
-const KeysSchema = z.object({
-    explicit: z
-        .record(
-            z.string().or(z.number()),
-            z.object({
-                table: z.string(),
-                id: z.string(),
-            })
-        )
-        .default({}),
-    composite: z
-        .array(
-            z.object({
-                table: z.string(),
-                id: z.string(),
-                key: z.record(z.string(), z.string().or(z.number())),
-            })
-        )
-        .default([]),
-    deleted: z.record(z.array(z.string())).default({}),
-})
-
-export class Keys implements Now.Internal.KeysRegistry {
-    private readonly file: ts.SourceFile
-    private readonly keys: Now.Internal.KeysRegistry
-    private readonly usedIds: Set<string> = new Set()
-
-    constructor(context: Context) {
-        this.file = Keys.getKeysFile(context)
-        this.keys = Keys.parseKeysFile(this.file)
-    }
-
-    private static parseKeysFile(keysFile: ts.SourceFile): Now.Internal.KeysRegistry {
-        const keysInterface = Keys.getOrCreateKeysInterface(keysFile)
-        return KeysSchema.parse(
-            parseType(keysInterface.getType(), keysInterface, (unparsableType) => {
-                if (unparsableType.isArray()) {
-                    return [] // If the keys file doesn't have composite keys, it will be an unparsable array so just return an empty one
-                } else {
-                    throw `Unparsable type in keys.ts: ${unparsableType.getText()}`
-                }
-            })
-        )
-    }
-
-    private static getKeysFile(context: Context): ts.SourceFile {
-        const keysFilePath = Keys.getKeysFilePath(context)
-        const keysFile =
-            context.compiler.addSourceFileAtPathIfExists(keysFilePath) ??
-            context.compiler.createSourceFile(keysFilePath, '', {
-                overwrite: true,
-                scriptKind: ts.ScriptKind.TS,
-            })
-
-        // Add global import if not already present
-        if (!keysFile.getImportDeclaration((i) => i.getModuleSpecifierValue() === KEYS_MODULE)) {
-            keysFile.addImportDeclaration({ moduleSpecifier: KEYS_MODULE })
-        }
-
-        return keysFile
-    }
-
-    public static getKeysFilePath(context: Context) {
-        return path.resolve(context.app.rootDir, context.app.config.generatedDir, KEYS_FILE_NAME)
-    }
-
-    private static getOrCreateKeysInterface(keysFile: ts.SourceFile) {
-        const declareGlobal =
-            keysFile.getModule('global') ??
-            keysFile.addModule({
-                name: 'global',
-                declarationKind: ts.ModuleDeclarationKind.Global,
-                hasDeclareKeyword: true,
-            })
-
-        const nowNamespace =
-            declareGlobal.getModule('Now') ??
-            declareGlobal.addModule({
-                name: 'Now',
-                declarationKind: ts.ModuleDeclarationKind.Namespace,
-            })
-
-        const internalNamespace =
-            nowNamespace.getModule('Internal') ??
-            nowNamespace.addModule({
-                name: 'Internal',
-            })
-
-        return (
-            internalNamespace.getInterface('Keys') ??
-            internalNamespace.addInterface({
-                name: 'Keys',
-                extends: (writer) => {
-                    writer.write('KeysRegistry')
-                },
-            })
-        )
-    }
-
-    private use(id: string) {
-        this.usedIds.add(id)
-        return id
-    }
-
-    get explicit() {
-        return this.keys.explicit
-    }
-
-    get composite() {
-        return this.keys.composite
-    }
-
-    get deleted() {
-        return this.keys.deleted
-    }
-
-    getSourceFile(): ts.SourceFile {
-        return this.file
-    }
-
-    getNextAvailableExplicitKey() {
-        for (let i = 0; ; i++) {
-            const key = `generated${i}`
-            if (!this.explicit[key]) {
-                return key
-            }
-        }
-    }
-
-    explicitKeyExists(key: string | number) {
-        return !!this.explicit[key]
-    }
-
-    getIdUsingExplicitKey(key: string | number) {
-        return this.explicit[key]?.id
-    }
-
-    findExplicitKeyById(id: string) {
-        return Object.entries(this.explicit).find(([, v]) => v.id === id)?.[0]
-    }
-
-    registerExplicitId(table: string, key: string | number, sysIdOverride?: string): string {
-        if (isGUID(key)) {
-            // WARNING:
-            //
-            // IT IS CRITICAL THAT KEYS ARE NOT REGISTERED FOR THINGS OUTSIDE OF THE APP. IF KEYS ARE
-            // REGISTERED FOR THINGS THAT COME FROM THE CORE PLATFORM OR SOME OTHER APP, THERE IS RISK
-            // THAT THEY WILL BE DELETED ACCIDENTALLY BY THE CUSTOMER.
-            //
-            // THIS CHECK IS HERE AS AN EXTRA DEFENSIVE MEASURE TO MAKE SURE EXTERNAL SYS IDS ARE NOT
-            // ACCIDENTALLY REGISTERED AS LOCAL KEYS.
-            //
-            // TODO: We need to come up with a different system for key registration where external
-            // keys can be resolved to sys IDs without registering them as local keys.
-            return this.use(this.explicit[key]?.id ?? key)
-        }
-
-        const existing = this.explicit[key]
-        if (existing) {
-            return this.use(existing.id)
-        }
-
-        if (sysIdOverride) {
-            const existingKey = this.findExplicitKeyById(sysIdOverride)
-            if (existingKey) {
-                const existingWithSysId = this.explicit[existingKey]!
-                if (existingKey !== (key as string | number)) {
-                    throw `ID '${sysIdOverride}' is already registered for key '${existingKey}', cannot register for key '${key}'`
-                }
-
-                return this.use(existingWithSysId.id)
-            }
-        }
-
-        const newKey = {
-            table,
-            id: isGUID(key) ? (key as string) : sysIdOverride ?? GUID(),
-        }
-
-        this.explicit[key] = newKey
-        return this.use(newKey.id)
-    }
-
-    registerCompositeId(table: string, key: Record<string, string | number>, sysIdOverride?: string): string {
-        const existing = this.composite.find((k) => k.table === table && _.isEqual(k.key, key))
-        if (existing) {
-            if (existing.table !== table) {
-                throw `Composite key ${key} is already registered for table '${existing.table}', cannot register for table '${table}'`
-            }
-
-            return this.use(existing.id)
-        }
-
-        const newKey = {
-            table,
-            id: sysIdOverride ?? GUID(),
-            key,
-        }
-
-        this.composite.push(newKey)
-        return this.use(newKey.id)
-    }
-
-    getUsedExplicitIds() {
-        return Object.fromEntries(Object.entries(this.explicit).filter(([, v]) => this.usedIds.has(v.id)))
-    }
-
-    getUsedCompositeIds() {
-        return this.composite.filter((v) => this.usedIds.has(v.id))
-    }
-
-    // TODO: This is called in multiple places and is not very cheap. We should consider optimization options.
-    getDeletedAndUnusedIds() {
-        return [
-            ...Object.values(this.explicit),
-            ...this.composite,
-            ...Object.entries(this.deleted).flatMap(([k, v]) => v.map((id) => ({ table: k, id }))),
-        ]
-            .filter((v) => !this.usedIds.has(v.id))
-            .reduce(
-                (deletedIds, v) => {
-                    deletedIds[v.table] = [...(deletedIds[v.table] ?? []), v.id]
-                    return deletedIds
-                },
-                {} as Record<string, string[]>
-            )
-    }
-
-    async format(formatter?: (file: ts.SourceFile) => Promise<any>) {
-        await formatter?.(this.file)
-    }
-
-    updateSourceFile() {
-        const newProperties: ts.OptionalKind<ts.PropertySignatureStructure>[] = []
-        const usedExplicitIds = this.getUsedExplicitIds()
-        const usedCompositeIds = this.getUsedCompositeIds()
-        const deletedOrUnusedIds = this.getDeletedAndUnusedIds()
-
-        if (Object.keys(usedExplicitIds).length > 0) {
-            newProperties.push({
-                name: 'explicit',
-                type: JSON.stringify(usedExplicitIds, undefined, 4),
-            })
-        }
-
-        if (usedCompositeIds.length > 0) {
-            newProperties.push({
-                name: 'composite',
-                type: JSON.stringify(usedCompositeIds, undefined, 4),
-            })
-        }
-
-        if (Object.keys(deletedOrUnusedIds).length > 0) {
-            newProperties.push({
-                name: 'deleted',
-                type: JSON.stringify(deletedOrUnusedIds, undefined, 4),
-            })
-        }
-
-        const keysInterface = Keys.getOrCreateKeysInterface(this.file)
-        keysInterface.getProperties().forEach((p) => p.remove())
-        keysInterface.addProperties(newProperties)
-    }
-}

package/src/TypeScript.ts

@@ -1,65 +0,0 @@
-import { ts, tsc } from '@servicenow/sdk-project'
-
-export function getValueDeclaration(node: ts.Node) {
-    const symbol = node.getSymbolOrThrow(`Expected identifier to have symbol: ${node.getText()}`)
-    const valueDeclaration = getValueDeclarationFromSymbolOrAlias(symbol)
-
-    if (!ts.Node.isShorthandPropertyAssignment(valueDeclaration)) {
-        return valueDeclaration
-    }
-
-    const valueSymbol = valueDeclaration.getValueSymbol()
-    if (!valueSymbol) {
-        throw `Expected value declaration for shorthand property assignment to have value symbol: ${valueDeclaration.getText()}`
-    }
-
-    return getValueDeclarationFromSymbolOrAlias(valueSymbol)
-}
-
-function getValueDeclarationFromSymbolOrAlias(symbol: ts.Symbol) {
-    const valueDeclaration = symbol.getValueDeclaration() ?? symbol.getAliasedSymbol()?.getValueDeclaration()
-    if (!valueDeclaration) {
-        throw Error(`No value declaration found for symbol: ${symbol.getName()}`)
-    }
-
-    return valueDeclaration
-}
-
-export function parseType(
-    type: ts.Type,
-    location: ts.Node,
-    unparsableTypeHandler: (unparsableType: ts.Type) => unknown = (unparsableType) => {
-        throw `Unparsable type: ${unparsableType.getText()}`
-    }
-): unknown {
-    if (type.isLiteral()) {
-        return type.getLiteralValueOrThrow()
-    } else if (type.isTuple()) {
-        return type.getTupleElements().map((e) => parseType(e, location, unparsableTypeHandler))
-    } else if (type.isObject() && !type.isArray()) {
-        return type.getProperties().reduce(
-            (result, property) => ({
-                ...result,
-                [property.getName()]: parseType(property.getTypeAtLocation(location), location, unparsableTypeHandler),
-            }),
-            {}
-        )
-    } else {
-        return unparsableTypeHandler(type)
-    }
-}
-
-export function traverseNode(node: ts.Node, visitor: (node: ts.Node) => void) {
-    node.forEachChild((child) => {
-        traverseNode(child, visitor)
-    })
-
-    visitor(node)
-}
-
-export function createPropertyIdentifier(name: string) {
-    //Test that this is going to be a valid javascript property name (aaa, _aaa, 1, aaa1).  If so use as identifier (aaa: ...) or as a string literal property ('1aaa': ...)
-    return /^((?!\d)[\w$]+|\d+)$/i.test(name)
-        ? tsc.factory.createIdentifier(name)
-        : tsc.factory.createStringLiteral(name)
-}

package/src/XML.ts

@@ -1,98 +0,0 @@
-import { Action, type Context } from './plugins'
-import { create } from 'xmlbuilder2'
-import type { XMLBuilder } from 'xmlbuilder2/lib/interfaces'
-import { maybeGetFieldToTagMap } from './util/RuntimeTableSchema'
-
-export type XmlValue = string | number | boolean
-
-export function isValidXmlValue(value: unknown): value is XmlValue {
-    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
-}
-
-export function unloadBuilder(context: Context) {
-    const xml = create({ version: '1.0' }).ele('record_update')
-    const end = () => xml.end({ prettyPrint: true }).replaceAll(' ', ' ')
-
-    // Root Builder
-    return {
-        xml,
-        end,
-        record: (tableName: string, id: string | number, action: Action = 'INSERT_OR_UPDATE') => {
-            const rec = recordXml(xml, tableName, id, { attr: { action }, context })
-            rec.addSysScope(context)
-            return rec
-        },
-    }
-}
-
-/**
- * If the code contains the character sequence ']]>' it will be parsed as the end of
- * the CDATA section. To avoid this, we need to split the sequence by dividing the
- * content into two CDATA sections at that point.
- */
-export function sanitizeNestedCdataTags(content: string): string {
-    return content.replace(/]]>/g, ']]]]><![CDATA[>')
-}
-
-export function recordXml(
-    xml: XMLBuilder,
-    tableName: string,
-    id: string | number,
-    options: {
-        attr?: Record<string, string>
-        excludeScopeElement?: boolean
-        context?: Context
-    } = {}
-) {
-    const recordXml = xml.ele(tableName, options.attr || { action: 'INSERT_OR_UPDATE' })
-    recordXml.ele('sys_id', undefined).txt(`${id}`)
-    const fieldToTagMap = maybeGetFieldToTagMap(tableName, options.context?.getAllDocuments() || [])
-
-    // Record Builder
-    return {
-        fields(fields: Record<string, XmlValue>) {
-            for (const [columnName, value] of Object.entries(fields)) {
-                this.field(columnName, value)
-            }
-        },
-        field(columnName: string, value: unknown, attributes: Record<string, string> = {}, needsCDATA = false) {
-            if (!isValidXmlValue(value)) {
-                throw new Error(`Invalid XML value for "${columnName}" column: ${value}`)
-            }
-
-            let fieldXml
-            const tag = fieldToTagMap[columnName]
-            if (
-                columnName === 'script' ||
-                columnName === 'operation_script' ||
-                tag === 'script' ||
-                tag === 'html' ||
-                tag === 'xml' ||
-                needsCDATA
-            ) {
-                value = tag === 'xml' ? sanitizeNestedCdataTags(value as string) : value
-                fieldXml = recordXml.ele(columnName, attributes).dat(value as string)
-            } else {
-                /*
-                    &nbsp is not a predefined entity for XML, to overcome that the platform uses &amp;nbsp; in XMLs.  
-                    When we transform XML that contains &amp;nbsp; that translates to `&nbsp;`.
-                    But when fluent generates the XML from source it creates XML with &nbsp; which makes the XML invalid since `nbsp` is not defined.
-                    So we are replacing &nbsp; with &amp;nbsp; to ensure the XML is valid.
-                */
-                fieldXml = recordXml.ele(columnName, attributes).txt(`${value}`.replaceAll('&nbsp;', '&amp;nbsp;'))
-            }
-
-            // Field Builder
-            return {
-                choices(_choices: unknown) {
-                    fieldXml // TODO: Implement
-                },
-            }
-        },
-        addSysScope(context: Context) {
-            return recordXml
-                .ele('sys_scope', { display_value: context.app.config.scope })
-                .txt(context.app.config.scopeId)
-        },
-    }
-}

package/src/plugins/Context.ts

@@ -1,239 +0,0 @@
-import {
-    Document,
-    File,
-    LinkedDocument,
-    UnlinkedDocument,
-    Xml,
-    XmlData,
-    EntityData,
-    Arranged,
-    DocumentMap,
-    ExtractionResult,
-} from './behaviors'
-import { Keys } from '../Keys'
-import { Plugin } from './Plugin'
-import { FluentDiagnostic } from './Diagnostic'
-import { ProjectContext, SupportedNode, ts, type Diagnostic } from '@servicenow/sdk-project'
-
-// These are only imported so they can be referenced in JS docs
-import type {
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    Extractors,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    Composers,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    Arrangers,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    Serializers,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    Generators,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    Transformers,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    PostProcessors,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    Diagnostics,
-    Data,
-} from './behaviors'
-
-/**
- * The context object is a collection of contextual information and methods
- * passed into all the various behaviors of a plugin when those behaviors are
- * invoked. It is also used by the build system to orchestrate the build.
- *
- * Each behavioral method on the context can accept an array of plugins as
- * an argument to control which plugins are used for that request. If no
- * plugins are provided as input, all available plugins will be used.
- */
-export type Context = ProjectContext & {
-    /**
-     * Accepts a parsed XML object and returns an array of {@linkcode XmlData}
-     * extracted from that object.
-     *
-     * @see {@linkcode Extractors}
-     * @param xml The parsed XML to extract.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     * @returns an array of extracted data.
-     */
-    extractXml(this: Context, xml: Xml, plugins?: Plugin[]): XmlData[]
-
-    /**
-     * Accepts an AST node and returns a result containing an array of
-     * {@linkcode RawData} or {@linkcode EntityData} extracted from that node.
-     *
-     * @see {@linkcode Extractors}
-     * @param node The node to extract.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     * @returns a result object containing an array of extracted data.
-     */
-    extractAst(this: Context, node: ts.Node, plugins?: Plugin[]): ExtractionResult
-
-    /**
-     * Accepts an AST node and returns a result containing an array of
-     * {@linkcode RawData} extracted from that node.
-     *
-     * @see {@linkcode Extractors}
-     * @param node The node to extract.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     * @returns a result object containing an array of extracted data.
-     */
-    extractRaw(this: Context, node: ts.Node, plugins?: Plugin[]): ExtractionResult<Data>
-
-    /**
-     * Accepts an AST node and returns a result containing an array of
-     * {@linkcode EntityData} extracted from that node.
-     *
-     * @see {@linkcode Extractors}
-     * @param node The node to extract.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     * @returns a result object containing an array of extracted entities.
-     */
-    extractEntities(this: Context, node: ts.Node, plugins?: Plugin[]): ExtractionResult<EntityData>
-
-    /**
-     * Accepts an array of entity data and returns a {@linkcode LinkedDocument}
-     * array.
-     *
-     * @see {@linkcode Composers}
-     * @param data The {@linkcode EntityData} to compose.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     * @returns a {@linkcode LinkedDocument} array.
-     */
-    composeEntities(this: Context, data: EntityData[], plugins?: Plugin[]): Promise<LinkedDocument[]>
-
-    /**
-     * Accepts an array of XML data and returns an {@linkcode UnlinkedDocument}
-     * array.
-     *
-     * @see {@linkcode Composers}
-     * @param data The {@linkcode XmlData} to compose.
-     * @param context The {@linkcode Context} object.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     * @returns an {@linkcode UnlinkedDocument} array.
-     */
-    composeXml(this: Context, data: XmlData[], plugins?: Plugin[]): UnlinkedDocument[]
-
-    /**
-     * Accepts an array of documents and returns the same documents
-     * as unresolved arranged documents.
-     *
-     * @see {@linkcode Arrangers}
-     * @param documents The {@linkcode Document}s to arrange.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     * @returns a {@linkcode Document} & {@linkcode Arranged} array.
-     */
-    arrange<D extends Document>(this: Context, documents: D[], plugins?: Plugin[]): (D & Arranged<'unresolved'>)[]
-
-    /**
-     * Accepts an array of documents and returns an array of files.
-     *
-     * @see {@linkcode Serializers}
-     * @param documents The {@linkcode Document}s to serialize.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     * @returns a {@linkcode File} array.
-     */
-    serialize(this: Context, documents: (Document & Arranged)[], plugins?: Plugin[]): File[]
-
-    /**
-     * Accepts an array of documents, generates new AST nodes for those
-     * documents, and returns the same documents as linked documents.
-     *
-     * @see {@linkcode Generators}
-     * @param documents The {@linkcode Document}s to generate AST nodes for.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     * @returns a {@linkcode LinkedDocument} array.
-     */
-    generate(this: Context, documents: (UnlinkedDocument & Arranged)[], plugins?: Plugin[]): LinkedDocument[]
-
-    /**
-     * Accepts an array of linked documents and performs transformations on
-     * their original nodes to reflect any changes that may have been made to
-     * those documents' data.
-     *
-     * @see {@linkcode Transformers}
-     * @param documents The {@linkcode LinkedDocument}s to transform.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     */
-    transform(this: Context, documents: (LinkedDocument & Arranged)[], plugins?: Plugin[]): void
-
-    /**
-     * Accepts an array of extracted entities and runs post-processors on that
-     * data. Post-processors may perform a variety of arbitrary operations.
-     *
-     * @see {@linkcode PostProcessors}
-     * @param data The {@linkcode EntityData} to process.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     */
-    postProcessEntities(this: Context, data: EntityData[], plugins?: Plugin[]): void
-
-    /**
-     * Accepts an AST node and returns an array of {@linkcode FluentDiagnostic}s
-     * for that node.
-     *
-     * @see {@linkcode Diagnostics}
-     * @param node The node to get diagnostics for.
-     * @param plugins An optional array of {@linkcode Plugin}s to use.
-     * @returns an array of diagnostics.
-     */
-    getAstDiagnostics(this: Context, node: ts.Node, plugins?: Plugin[]): FluentDiagnostic[]
-
-    /**
-     * An object with metadata related to plugin like list of all tables that are claimed to be handled by a specific plugin, and
-     * the level of enforcement they apply to that table
-     * and API that the plugin is responsible for.
-     */
-    getPluginForTable(table: string): { logLevel: Diagnostic.Level; api: string } | undefined
-
-    /**
-     * An array of plugins that will be used (unless overridden) during various
-     * build process operations.
-     *
-     * @see {@link Plugin}
-     */
-    plugins: Plugin[]
-
-    /**
-     * An array of plugins which implement entity-handling behaviors which will
-     * be used during various build process operations. These plugins are always
-     * executed BEFORE the plugins in the {@link Context#plugins} array.
-     *
-     * @see {@link Plugin}
-     */
-    entityPlugins: Plugin[]
-
-    usageCount: { [key: string]: number }
-
-    /**
-     * Returns an object of XML file names that was marked as handled or ignored by code transformation during the build process.
-     */
-    getHandledXmls: () => Record<string, HandledInfo>
-
-    updateHandledXMLs: (xml: string | undefined, status: HandledStates, info?: string, node?: SupportedNode) => void
-    setAllDocuments: (documents: Document[]) => void
-    getAllDocuments: () => Document[]
-    getDocumentMap: () => DocumentMap
-    getDocument: (sysId: string, kind?: string) => Document | undefined
-
-    argTypesToFix: ts.CallExpression[]
-
-    fixTypeArguments: () => void
-
-    /**
-     * @deprecated Use the key methods on the context object instead.
-     */
-    keys: Keys
-
-    explicitKeyExists: Keys['explicitKeyExists']
-    getIdUsingExplicitKey: Keys['getIdUsingExplicitKey']
-    registerExplicitId: Keys['registerExplicitId']
-    registerCompositeId: Keys['registerCompositeId']
-    getDeletedAndUnusedIds: Keys['getDeletedAndUnusedIds']
-    getKeysSourceFile(): ts.SourceFile
-}
-
-export type HandledInfo = {
-    state: HandledStates
-    info?: string | undefined
-    node?: SupportedNode | undefined
-}
-export type HandledStates = 'handled' | 'handled as record' | 'ignored' | 'skipped' | 'unchanged'