@servicenow/sdk-build-plugins 3.0.2 → 4.0.0

package/src/column-plugin.ts

@@ -0,0 +1,506 @@
+import { CallExpressionShape, ObjectShape, Plugin, type Record } from '@servicenow/sdk-build-core'
+import { BooleanColumn, choiceDropdown, type choiceDropdownType, GenericColumn } from '@servicenow/sdk-core/runtime/db'
+import isEqual from 'lodash/isEqual'
+import { getChoiceRecords, getDocumentationRecords } from './column/column-to-record'
+import {
+    COLUMN_API_TO_TYPE,
+    COLUMN_TYPE_TO_API,
+    DEFAULT_COLUMN_CALCULATION,
+    getDefaultMaxLength,
+} from './column/column-helper'
+import { ModuleFunctionShape } from './server-module-plugin'
+import { generateDeprecatedDiagnostics } from './utils'
+
+const PLURAL_EQUALS_LABEL = [
+    's',
+    'ed',
+    'by',
+    'Active',
+    ')',
+    ' to',
+    ' with',
+    ' for',
+    ' in',
+    ' out',
+    ' use',
+    'Data',
+    ' data',
+]
+const PLURAL_SPECIAL_CASE_Y_TO_IES = ['ry', 'ty', 'dy', 'cy', 'fy', 'ly', 'ny']
+const PLURAL_SPECIAL_CASE_ADD_ES = ['x', 'sh', 'ch', 'z']
+
+const columnAliases = {
+    readOnly: ['read_only'],
+    functionDefinition: ['function_definition'],
+    tableReference: ['table_reference'],
+    elementReference: ['element_reference'],
+    spellCheck: ['spell_check'],
+    xmlView: ['xml_view'],
+    textIndex: ['text_index'],
+    dynamicValueDefinitions: ['dynamic_value_definitions'],
+    referenceFloats: ['reference_floats'],
+    dynamicCreationScript: ['dynamic_creation_script'],
+    dynamicCreation: ['dyamic_creation'], // maintaining backwards compatibility with typo
+    referenceKey: ['reference_key'],
+    referenceQual: ['reference_qual'],
+    columnType: ['column_type'],
+}
+
+const calculationAliases = {
+    calculatedValue: ['calculated_value'],
+    columnName: ['column_name'],
+}
+
+const choiceAliases = {
+    dependentValue: ['dependent_value'],
+    inactiveOnUpdate: ['inactive_on_update'],
+}
+
+const documentationAliases = {
+    urlTarget: ['url_target'],
+}
+
+export const ColumnPlugin = Plugin.create({
+    name: 'ColumnPlugin',
+    records: {
+        sys_choice: { coalesce: ['name', 'element', 'value'] },
+        sys_documentation: { coalesce: ['name', 'element', 'language'] },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { factory, diagnostics, config }) {
+                const callee = callExpression.getCallee()
+                if (!(callee in COLUMN_API_TO_TYPE) && !(callee === GenericColumn.name)) {
+                    return { success: false }
+                }
+
+                const column = callExpression.getArgument(0).asObject().withAliasedKeys(columnAliases)
+                generateDeprecatedDiagnostics(column, diagnostics)
+                if (!column.has('table') || !column.has('name')) {
+                    return { success: false }
+                }
+
+                const documentationRecords = getDocumentationRecords(
+                    callExpression,
+                    documentationAliases,
+                    factory,
+                    diagnostics,
+                    true
+                )
+                const choiceRecords = getChoiceRecords(callExpression, choiceAliases, factory, diagnostics)
+
+                const columnType = COLUMN_API_TO_TYPE[callee] ?? column.get('columnType').asString().getValue()
+                return {
+                    success: true,
+                    value: factory
+                        .createRecord({
+                            source: callExpression,
+                            table: 'sys_dictionary',
+                            properties: column.transform(({ $ }) => ({
+                                name: $.from('table'),
+                                element: $.from('name'),
+                                internal_type: $.val(columnType),
+                                active: $.toBoolean().def(true),
+                                array: $.toBoolean().def(false),
+                                attributes: $.map((attributes) => {
+                                    if (!attributes.isObject()) {
+                                        return undefined
+                                    }
+                                    const attributesObj = attributes.asObject().getValue()
+                                    return Object.entries(attributesObj)
+                                        .map(([key, value]) => `${key}=${value}`)
+                                        .join(',')
+                                }).def(''),
+                                audit: $.toBoolean().def(false),
+                                reference_cascade_rule: $.from('cascadeRule'),
+                                default_value: $.from('default'),
+                                display: $.toBoolean().def(false),
+                                dynamic_creation: $.from('dynamicCreation').toBoolean(),
+                                dynamic_creation_script: $.from('dynamicCreationScript'),
+                                reference_floats: $.from('referenceFloats'),
+                                reference_key: $.from('referenceKey'),
+                                reference_qual: $.from('referenceQual'),
+                                calculation: $.from('dynamicValueDefinitions')
+                                    .map((dynamicValueDefinitions) => {
+                                        if (
+                                            dynamicValueDefinitions.ifObject()?.get('type').ifString()?.getValue() !==
+                                            'calculated_value'
+                                        ) {
+                                            return undefined
+                                        }
+                                        const dynamicValueObject = dynamicValueDefinitions
+                                            .asObject()
+                                            .withAliasedKeys(calculationAliases)
+                                        generateDeprecatedDiagnostics(dynamicValueObject, diagnostics)
+                                        const calculatedValue = dynamicValueObject.get('calculatedValue')
+
+                                        if (calculatedValue.isUnresolved()) {
+                                            diagnostics.error(
+                                                calculatedValue.getOriginalNode(),
+                                                `Unable to resolve the script reference, ensure the imported module is within the ${config.serverModulesDir} directory.`
+                                            )
+                                        }
+
+                                        return (
+                                            calculatedValue
+                                                .if(ModuleFunctionShape)
+                                                ?.toString((n) => `${n}({{PARAMS}})`, ['current']) ?? calculatedValue
+                                        )
+                                    })
+                                    .toCdata(),
+                                choice: $.from('dropdown')
+                                    .map((d) =>
+                                        d.isString()
+                                            ? Math.max(choiceDropdown.indexOf(d.getValue() as choiceDropdownType), 0)
+                                            : undefined
+                                    )
+                                    .def(0),
+                                choice_table: $.from('dynamicValueDefinitions').map((dynamicValueDefinitions) =>
+                                    dynamicValueDefinitions.ifObject()?.get('type').ifString()?.getValue() ===
+                                    'choices_from_other_table'
+                                        ? dynamicValueDefinitions.asObject().get('table').ifString()
+                                        : undefined
+                                ),
+                                virtual: $.from('dynamicValueDefinitions')
+                                    .map((dynamicValueDefinitions) => {
+                                        const calculationType = dynamicValueDefinitions
+                                            .ifObject()
+                                            ?.get('type')
+                                            .ifString()
+                                            ?.getValue()
+                                        if (!calculationType) {
+                                            return undefined
+                                        }
+                                        return calculationType === 'calculated_value'
+                                    })
+                                    .toBoolean(),
+                                choice_field: $.from('dynamicValueDefinitions').map((dynamicValueDefinitions) =>
+                                    dynamicValueDefinitions.ifObject()?.get('type').ifString()?.getValue() ===
+                                    'choices_from_other_table'
+                                        ? dynamicValueDefinitions.asObject().get('field').ifString()
+                                        : undefined
+                                ),
+                                dependent: $.from('dynamicValueDefinitions').map((dynamicValueDefinitions) => {
+                                    if (
+                                        dynamicValueDefinitions.ifObject()?.get('type').ifString()?.getValue() !==
+                                        'dependent_field'
+                                    ) {
+                                        return undefined
+                                    }
+                                    const dynamicValueObject = dynamicValueDefinitions
+                                        .asObject()
+                                        .withAliasedKeys(calculationAliases)
+                                    generateDeprecatedDiagnostics(dynamicValueObject, diagnostics)
+                                    return dynamicValueObject.get('columnName').ifString()
+                                }),
+                                dependent_on_field: $.from('dynamicValueDefinitions').map((dynamicValueDefinitions) => {
+                                    if (
+                                        dynamicValueDefinitions.ifObject()?.get('type').ifString()?.getValue() !==
+                                        'dependent_field'
+                                    ) {
+                                        return undefined
+                                    }
+                                    const dynamicValueObject = dynamicValueDefinitions
+                                        .asObject()
+                                        .withAliasedKeys(calculationAliases)
+                                    generateDeprecatedDiagnostics(dynamicValueObject, diagnostics)
+                                    return dynamicValueObject.get('columnName').ifString()
+                                }),
+                                use_dependent_field: $.from('dynamicValueDefinitions')
+                                    .map(
+                                        (dynamicValueDefinitions) =>
+                                            dynamicValueDefinitions.ifObject()?.get('type').ifString()?.getValue() ===
+                                            'dependent_field'
+                                    )
+                                    .def(false),
+                                element_reference: $.from('elementReference').toBoolean().def(false),
+                                function_definition: $.from('functionDefinition'),
+                                function_field: $.from('functionDefinition')
+                                    .map((f) => f.isString() && f.getValue() !== '')
+                                    .def(false),
+                                column_label: $.from('label')
+                                    .map((label) => (label.isString() ? label.asString() : undefined))
+                                    .def(column.get('name').asString()),
+                                mandatory: $.toBoolean().def(false),
+                                max_length: $.from('maxLength')
+                                    .map(
+                                        (maxLength) =>
+                                            maxLength.ifNumber()?.getValue() ?? maxLength.ifString()?.getValue()
+                                    )
+                                    .def(getDefaultMaxLength(columnType)),
+                                primary: $.toBoolean().def(false),
+                                read_only: $.from('readOnly').toBoolean().def(false),
+                                reference: $.from('referenceTable'),
+                                spell_check: $.from('spellCheck').toBoolean().def(false),
+                                table_reference: $.from('tableReference').toBoolean().def(false),
+                                text_index: $.from('textIndex').toBoolean().def(false),
+                                unique: $.toBoolean().def(false),
+                                widget: $,
+                                xml_view: $.from('xmlView').toBoolean().def(false),
+                            })),
+                        })
+                        .with(...documentationRecords, ...choiceRecords),
+                }
+            },
+        },
+    ],
+})
+
+export function columnToCallExpression(
+    column: Record,
+    related: { choices: Record[]; documentation: Record[] }
+): CallExpressionShape {
+    const callExpression = COLUMN_TYPE_TO_API[column.get('internal_type').asString().getValue()] ?? GenericColumn.name
+    const { choices, documentation } = related
+    return new CallExpressionShape({
+        source: column,
+        callee: callExpression,
+        args: [
+            column
+                .transform(({ $ }) => ({
+                    active: $.toBoolean().def(true),
+                    array: $.toBoolean().def(false),
+                    attributes: $.map((attributes) => {
+                        if (!attributes.isString()) {
+                            return undefined
+                        }
+                        const result = {}
+                        attributes
+                            .toString()
+                            .getValue()
+                            .split(',')
+                            .forEach((attr) => {
+                                if (attr === '') {
+                                    return
+                                }
+                                const [key, value] = attr.split('=').map((s) => s.trim())
+                                if (value === 'true') {
+                                    result[key!] = true
+                                } else if (value === 'false') {
+                                    result[key!] = false
+                                } else {
+                                    result[key!] = value
+                                }
+                            })
+                        return result
+                    }).def({
+                        edge_encryption_enabled: true,
+                    }),
+                    audit: $.toBoolean().def(false),
+                    cascadeRule: $.from('reference_cascade_rule').def(''),
+                    columnType: callExpression === GenericColumn.name ? $.from('internal_type') : $.val(undefined),
+                    default: $.from('default_value')
+                        .map((defaultValue) => {
+                            // TODO Solve default type inference generally
+                            if (callExpression === BooleanColumn.name) {
+                                if (defaultValue.isBoolean()) {
+                                    return defaultValue
+                                } else if (defaultValue.isString()) {
+                                    const defaultString = defaultValue.asString().getValue().trim()
+                                    if (defaultString === 'true') {
+                                        return true
+                                    }
+                                    if (defaultString === 'false') {
+                                        return false
+                                    }
+                                }
+                            }
+                            if (defaultValue.isNumber()) {
+                                return defaultValue.getValue().toString()
+                            }
+                            return defaultValue
+                        })
+                        .def(''),
+                    choices: choices.length
+                        ? $.val(
+                              choices.reduce(
+                                  (acc, choiceRecord) => {
+                                      const value = choiceRecord.get('value').asString().getValue()
+                                      acc[value] = choiceRecord
+                                          .transform(({ $ }) => ({
+                                              label: $,
+                                              sequence: $.map((sequence) => {
+                                                  if (sequence.isNumber()) {
+                                                      return sequence
+                                                  } else if (sequence.isString()) {
+                                                      const sequenceVal = sequence.asString().getValue().trim()
+                                                      return sequenceVal !== '' && !isNaN(Number(sequenceVal))
+                                                          ? Number(sequenceVal)
+                                                          : undefined
+                                                  }
+                                                  return undefined
+                                              }),
+                                              dependentValue: $.from('dependent_value').map((depVal) => {
+                                                  if (depVal.isNumber()) {
+                                                      return depVal.asNumber().getValue()
+                                                  } else if (depVal.isString()) {
+                                                      const depValue = depVal.asString().getValue().trim()
+                                                      return (
+                                                          (isNaN(Number(depValue)) ? depValue : Number(depValue)) ||
+                                                          undefined
+                                                      )
+                                                  }
+                                                  return undefined
+                                              }),
+                                              inactive: $.toBoolean().def(false),
+                                              inactiveOnUpdate: $.from('inactive_on_update').toBoolean().def(false),
+                                              hint: $.def(''),
+                                              // TODO Make default language configurable
+                                              language: $.def('en'),
+                                          }))
+                                          .withAliasedKeys(choiceAliases)
+                                      return acc
+                                  },
+                                  {} as globalThis.Record<string, ObjectShape>
+                              )
+                          )
+                        : $.val(undefined),
+                    dropdown: $.from('choice')
+                        .map((choice) => {
+                            let dropdownIndex = -1
+                            if (choice.isNumber()) {
+                                dropdownIndex = choice.asNumber().getValue()
+                            } else if (choice.isString()) {
+                                const parsedChoice = Number(choice.asString().getValue())
+                                if (!isNaN(parsedChoice)) {
+                                    dropdownIndex = parsedChoice
+                                }
+                            }
+                            return dropdownIndex !== -1 ? choiceDropdown[dropdownIndex] : undefined
+                        })
+                        .def('none'),
+                    dynamicValueDefinitions: $.from('calculation', 'choice_table', 'choice_field', 'dependent').map(
+                        (calculation, choiceTable, choiceField, dependent) => {
+                            if (
+                                calculation.ifString()?.getValue() &&
+                                calculation.asString().getValue() !== DEFAULT_COLUMN_CALCULATION
+                            ) {
+                                return new ObjectShape({
+                                    source: calculation,
+                                    properties: {
+                                        type: 'calculated_value',
+                                        calculatedValue: calculation,
+                                    },
+                                }).withAliasedKeys(calculationAliases)
+                            }
+                            if (choiceTable.ifString()?.getValue() && choiceField.ifString()?.getValue()) {
+                                return {
+                                    type: 'choices_from_other_table',
+                                    table: choiceTable.asString().getValue(),
+                                    field: choiceField.asString().getValue(),
+                                }
+                            }
+                            if (dependent.ifString()?.getValue()) {
+                                return new ObjectShape({
+                                    source: dependent,
+                                    properties: {
+                                        type: 'dependent_field',
+                                        columnName: dependent.asString().getValue(),
+                                    },
+                                }).withAliasedKeys(calculationAliases)
+                            }
+                            return undefined
+                        }
+                    ),
+                    elementReference: $.from('element_reference').toBoolean().def(false),
+                    functionDefinition: $.from('function_definition').def(''),
+                    label:
+                        documentation.length &&
+                        !isDefaultDocumentation(column.get('element').asString().getValue(), documentation)
+                            ? $.val(
+                                  documentation.map((doc) =>
+                                      doc
+                                          .transform(({ $ }) => ({
+                                              hint: $.def(''),
+                                              help: $.def(''),
+                                              label: $.def(''),
+                                              plural: $.def(''),
+                                              language: $.def(''),
+                                              url: $.def(''),
+                                              urlTarget: $.from('url_target').def(''),
+                                          }))
+                                          .withAliasedKeys(documentationAliases)
+                                  )
+                              )
+                            : $.from('column_label').def(column.get('element').getValue()),
+                    mandatory: $.toBoolean().def(false),
+                    maxLength: $.from('max_length')
+                        .map((maxLength) => {
+                            if (maxLength.isNumber()) {
+                                return maxLength.asNumber()
+                            }
+                            if (maxLength.isString()) {
+                                const numVal = parseInt(maxLength.asString().getValue())
+                                return isNaN(numVal) ? maxLength : numVal
+                            }
+                            return undefined
+                        })
+                        .def(getDefaultMaxLength(column.get('internal_type').asString().getValue())),
+                    primary: $.toBoolean().def(false),
+                    readOnly: $.from('read_only').toBoolean().def(false),
+                    referenceTable: $.from('reference').def(''),
+                    referenceFloats: $.from('reference_floats').toBoolean().def(false),
+                    referenceKey: $.from('reference_key').def(''),
+                    referenceQual: $.from('reference_qual').def(''),
+                    dynamicCreation: $.from('dynamic_creation').toBoolean().def(false),
+                    dynamicCreationScript: $.from('dynamic_creation_script').def(''),
+                    spellCheck: $.from('spell_check').toBoolean().def(false),
+                    tableReference: $.from('table_reference').toBoolean().def(false),
+                    textIndex: $.from('text_index').toBoolean().def(false),
+                    unique: $.toBoolean().def(false),
+                    widget: $.def(''),
+                    xmlView: $.from('xml_view').toBoolean().def(false),
+                }))
+                .withAliasedKeys(columnAliases),
+        ],
+    })
+}
+
+export function generatePlural(label: string): string | undefined {
+    if (!label) {
+        return undefined
+    }
+
+    for (const suffix of PLURAL_EQUALS_LABEL) {
+        if (label.endsWith(suffix)) {
+            return label
+        }
+    }
+    for (const suffix of PLURAL_SPECIAL_CASE_Y_TO_IES) {
+        if (label.endsWith(suffix)) {
+            return label.substring(0, label.lastIndexOf('y')) + 'ies'
+        }
+    }
+    for (const suffix of PLURAL_SPECIAL_CASE_ADD_ES) {
+        if (label.endsWith(suffix)) {
+            return label + 'es'
+        }
+    }
+
+    return label + 's'
+}
+
+export function isDefaultDocumentation(columnName: string, documentation: Record[]): boolean {
+    if (documentation.length !== 1) {
+        return false
+    }
+    const doc = documentation[0]!.asObject().getValue() as globalThis.Record<string, unknown>
+    const label = (doc['label'] as string | undefined) ?? columnName
+    const defaultRecord: globalThis.Record<string, unknown> = {
+        name: doc['name'],
+        element: doc['element'],
+        label,
+        plural: generatePlural(label),
+        // TODO make default language configurable
+        language: 'en',
+    }
+    const optionalFields = ['hint', 'help', 'url', 'url_target', 'sys_policy'] as const
+    optionalFields.forEach((field) => {
+        if (field in doc) {
+            defaultRecord[field] = ''
+        }
+    })
+    return isEqual(defaultRecord, doc)
+}

package/src/cross-scope-privilege-plugin.ts

@@ -0,0 +1,82 @@
+import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
+import { NowIdShape } from './now-id-plugin'
+import { generateDeprecatedDiagnostics } from './utils'
+
+const crossScopeAliases = {
+    targetName: ['target_name'],
+    targetScope: ['target_scope'],
+    targetType: ['target_type'],
+}
+
+/**
+ * Creates a Cross Scope Privilege record (`sys_scope_privilege`).
+ *
+ * @see https://docs.servicenow.com/csh?topicname=c_CrossScopePrivilegeRecord.html&version=latest
+ *
+ * @param config - an object containing the following properties:
+ *   * **$id** - unique id for the record, typically using `Now.ID["value"]`
+ *   * **operation** - operation the script performs on the target
+ *   * **status** - authorization for this record
+ *   * **targetName** - name of the table, script include, or script object being requested
+ *   * **targetScope** - application whose resources are being requested
+ *   * **targetType** - type of request
+ */
+export const CrossScopePrivilegePlugin = Plugin.create({
+    name: 'CrossScopePrivilegePlugin',
+    records: {
+        sys_scope_privilege: {
+            toShape(record) {
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'CrossScopePrivilege',
+                        args: [
+                            record
+                                .transform(({ $ }) => ({
+                                    $id: $.val(NowIdShape.from(record)),
+                                    operation: $,
+                                    status: $,
+                                    targetName: $.from('target_name'),
+                                    targetScope: $.from('target_scope'),
+                                    targetType: $.from('target_type'),
+                                }))
+                                .withAliasedKeys(crossScopeAliases),
+                        ],
+                    }),
+                }
+            },
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            toRecord(callExpression, { factory, config, diagnostics }) {
+                if (callExpression.getCallee() !== 'CrossScopePrivilege') {
+                    return { success: false }
+                }
+
+                const csp = callExpression.getArgument(0).asObject().withAliasedKeys(crossScopeAliases)
+                generateDeprecatedDiagnostics(csp, diagnostics)
+
+                return {
+                    success: true,
+                    value: factory.createRecord({
+                        source: callExpression,
+                        table: 'sys_scope_privilege',
+                        explicitId: csp.get('$id'),
+                        properties: csp.transform(({ $ }) => ({
+                            operation: $,
+                            status: $,
+                            target_name: $.from('targetName'),
+                            target_scope: $.from('targetScope'),
+                            target_type: $.from('targetType'),
+                            source_scope: $.val(config.scopeId),
+                        })),
+                    }),
+                }
+            },
+        },
+    ],
+})

package/src/html-import-plugin.ts

@@ -0,0 +1,79 @@
+import { path as pathModule, Plugin, Shape, StringShape, ts } from '@servicenow/sdk-build-core'
+import { applyPathMappings } from './utils'
+
+const HTML_IMPORT_PREFIX = `<!-- @fluent-import-html`
+const HTML_IMPORT_WARNING = `WARNING: This file was imported from the output of a static build. Modifications of any kind are likely to result in unintended behavior. In most cases, you should edit the source file of the HTML imported below. If you are absolutely certain you want to take control of this HTML, you can remove this comment to prevent the SDK from regenerating it. However, you will then be responsible for the management of this HTML in your Fluent file. -->`
+
+const getDeclarationAndModuleSpecifierIfHtml = (node: ts.Node): [ts.ImportDeclaration, string] | null => {
+    const [importClause] = node.getSymbol()?.getDeclarations() ?? []
+    if (!importClause) {
+        return null
+    }
+
+    const importDeclaration = importClause.getParent()?.asKind(ts.SyntaxKind.ImportDeclaration)
+    if (!importDeclaration) {
+        return null
+    }
+
+    const moduleSpecifier = importDeclaration.getModuleSpecifierValue()
+    if (!moduleSpecifier.endsWith('.html')) {
+        return null
+    }
+
+    return [importDeclaration, moduleSpecifier]
+}
+
+export const HtmlImportPlugin = Plugin.create({
+    name: 'HtmlImportPlugin',
+    shapes: [
+        {
+            shape: StringShape,
+            commit(shape, target) {
+                const results = getDeclarationAndModuleSpecifierIfHtml(target)
+                if (!results) {
+                    return { success: false }
+                }
+                const shapeContent = shape.getValue().trim()
+                // skip committing if the content has the import directive comment
+                return { success: shapeContent.startsWith(HTML_IMPORT_PREFIX) }
+            },
+        },
+    ],
+    nodes: [
+        {
+            node: 'Identifier',
+            fileTypes: ['fluent'],
+            toShape(node, context) {
+                const { project, diagnostics, config } = context
+                const results = getDeclarationAndModuleSpecifierIfHtml(node)
+                if (!results) {
+                    return { success: false }
+                }
+                const [importDeclaration, moduleSpecifier] = results
+
+                if (!/^\.\.?\/.*$/.test(moduleSpecifier.trim())) {
+                    diagnostics.error(importDeclaration, 'import must be a relative path')
+                    return { success: false }
+                }
+
+                const currentDir = pathModule.dirname(node.getSourceFile().getFilePath())
+                const resolvedPath = project.resolvePath(currentDir, moduleSpecifier)
+                const projectRelativePath = pathModule.relative(project.getRootDir(), resolvedPath)
+
+                if (projectRelativePath.startsWith('..')) {
+                    diagnostics.error(importDeclaration, `import not within project: ${moduleSpecifier}`)
+                    return { success: false }
+                }
+
+                const mappedPath = applyPathMappings(projectRelativePath, config.staticContentPaths)
+                const htmlFile = project.addFile(mappedPath, { resolveDependencies: false, excludeFromCompiler: true })
+
+                return {
+                    success: true,
+                    // add a directive comment to the imported HTML content to warn users against modifing it
+                    value: Shape.from(node, `${HTML_IMPORT_PREFIX} ${HTML_IMPORT_WARNING}\n${htmlFile.getContent()}`),
+                }
+            },
+        },
+    ],
+})