@wix/zero-config-implementation 1.95.0 → 1.97.0

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.95.0",
+  "version": "1.97.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -106,5 +106,5 @@
       ]
     }
   },
-  "falconPackageHash": "831bcccde22937359efc18de9a5b8b4e52d3ca3fa6ebdbdd9bcb4a65"
+  "falconPackageHash": "0b3ebaeffed6f192d5ccd84f8598e0e524b0edb36eb3ca0961bab4c7"
 }

package/src/converters/a11y-builder.test.ts

@@ -0,0 +1,32 @@
+import { DATA } from '@wix/react-component-schema'
+import { describe, expect, it } from 'vitest'
+import type { PropWriteInfo, TrackingStores } from '../information-extractors/react/types'
+import { collectUsedA11yAttributes } from './a11y-builder'
+
+function propUsagesFor(propPaths: string[]): TrackingStores['propUsages'] {
+  const emptyWriteInfo = (): PropWriteInfo => ({ elements: new Map(), attributes: new Map() })
+  return new Map(propPaths.map((propPath) => [propPath, emptyWriteInfo()]))
+}
+
+describe('collectUsedA11yAttributes', () => {
+  it('returns an empty array when propUsages or propPath is unavailable', () => {
+    expect(collectUsedA11yAttributes(undefined, 'props.a11y')).toEqual([])
+    expect(collectUsedA11yAttributes(propUsagesFor(['props.a11y.role']), undefined)).toEqual([])
+  })
+
+  it('returns an empty array when no accessibility fields are recorded', () => {
+    expect(collectUsedA11yAttributes(propUsagesFor([]), 'props.a11y')).toEqual([])
+  })
+
+  it('allows only the current editor-configurable fields', () => {
+    const allAttributes = Object.values(DATA.A11Y_ATTRIBUTES).map((attribute) => `props.a11y.${attribute}`)
+
+    expect(collectUsedA11yAttributes(propUsagesFor(allAttributes), 'props.a11y')).toEqual(['ariaLabel', 'tag'])
+  })
+
+  it('keeps allowed fields in schema order', () => {
+    const propUsages = propUsagesFor(['props.a11y.tag', 'props.a11y.role', 'props.a11y.ariaLabel'])
+
+    expect(collectUsedA11yAttributes(propUsages, 'props.a11y')).toEqual(['ariaLabel', 'tag'])
+  })
+})

package/src/converters/a11y-builder.ts

@@ -1,25 +1,31 @@
 import { DATA } from '@wix/react-component-schema'
 import type { TrackingStores } from '../information-extractors/react'
 
+type A11yAttribute = (typeof DATA.A11Y_ATTRIBUTES)[keyof typeof DATA.A11Y_ATTRIBUTES]
+
+const EDITOR_CONFIGURABLE_A11Y_ATTRIBUTES: ReadonlySet<A11yAttribute> = new Set([
+  DATA.A11Y_ATTRIBUTES.ariaLabel,
+  DATA.A11Y_ATTRIBUTES.tag,
+])
+
 /**
- * Walks the known A11y attributes (from DATA.A11Y_ATTRIBUTES) in deterministic
- * enum order and returns the subset whose `${propPath}.${attribute}` key was
- * recorded in propUsages by the prop-tracker. When propUsages or propPath is
- * unavailable, returns an empty array — per the schema, an empty list means
- * "all possible A11Y values", which is a safe default.
+ * Returns the editor-configurable attributes the component reads, in schema
+ * order. The caller must omit the a11y data item when this returns an empty
+ * list because the manifest schema interprets an empty list as all attributes.
  */
 export function collectUsedA11yAttributes(
   propUsages: TrackingStores['propUsages'] | undefined,
   propPath: string | undefined,
-): (typeof DATA.A11Y_ATTRIBUTES)[keyof typeof DATA.A11Y_ATTRIBUTES][] {
+): A11yAttribute[] {
   if (!propUsages || !propPath) return []
 
-  const used: (typeof DATA.A11Y_ATTRIBUTES)[keyof typeof DATA.A11Y_ATTRIBUTES][] = []
+  const usedAttributes: A11yAttribute[] = []
   for (const attribute of Object.values(DATA.A11Y_ATTRIBUTES)) {
-    if (attribute === DATA.A11Y_ATTRIBUTES.Unknown_AriaAttributes) continue
+    if (!EDITOR_CONFIGURABLE_A11Y_ATTRIBUTES.has(attribute)) continue
     if (propUsages.has(`${propPath}.${attribute}`)) {
-      used.push(attribute)
+      usedAttributes.push(attribute)
     }
   }
-  return used
+
+  return usedAttributes
 }

package/src/converters/to-editor-component.test.ts

@@ -54,6 +54,45 @@ function createComponent(rootElement: ExtractedElement): ComponentInfoWithCss {
   }
 }
 
+function createComponentWithA11yUsages(propPaths: string[]): ComponentInfoWithCss {
+  return {
+    ...createComponent(createElementWithDisplayMatcher('div', matcherDataFromCss(''))),
+    props: {
+      a11y: {
+        name: 'a11y',
+        type: 'A11y',
+        required: false,
+        resolvedType: { kind: 'semantic', value: 'A11y', source: '@wix/editor-react-types' },
+        propPath: 'props.a11y',
+        logicOnly: false,
+      },
+    },
+    propUsages: new Map(propPaths.map((propPath) => [propPath, { elements: new Map(), attributes: new Map() }])),
+  }
+}
+
+describe('toEditorReactComponent accessibility conversion', () => {
+  it('omits the a11y item when the component reads only component-owned fields', () => {
+    const component = createComponentWithA11yUsages(['props.a11y.role', 'props.a11y.tabIndex'])
+
+    expect(toEditorReactComponent(component).editorElement?.data?.a11y).toBeUndefined()
+  })
+
+  it('emits only the allowed fields when reads are mixed', () => {
+    const component = createComponentWithA11yUsages([
+      'props.a11y.role',
+      'props.a11y.ariaLabel',
+      'props.a11y.ariaExpanded',
+      'props.a11y.tag',
+    ])
+
+    expect(toEditorReactComponent(component).editorElement?.data?.a11y).toMatchObject({
+      dataType: 'a11y',
+      a11y: { attributes: ['ariaLabel', 'tag'] },
+    })
+  })
+})
+
 function createSemanticElement({
   traceId,
   name,
@@ -369,26 +408,36 @@ function cssInfoFromStylesheet(cssString: string): ExtractedCssInfo {
   return { filePath: 'property-tokens.css', api, properties, customProperties, isCssModule: false }
 }
 
-function createComponentWithCss(cssString: string): ComponentInfoWithCss {
+function createComponentWithStylesheets(
+  cssStrings: string[],
+  matchedCustomProperties: Record<string, string> = {},
+): ComponentInfoWithCss {
+  const matcherData: MatchedCssData = { matches: [], customProperties: matchedCustomProperties }
   const rootElement: ExtractedElement = {
     traceId: 'trace-root',
     name: 'root',
     tag: 'div',
     attributes: {},
-    extractorData: new Map<string, unknown>(),
+    extractorData: new Map<string, unknown>([['css-matcher', matcherData]]),
     children: [],
   }
 
   return {
-    componentName: 'PropertyTokens',
+    componentName: 'MultiStylesheet',
     props: {},
     elements: [rootElement],
     propUsages: new Map(),
-    css: [cssInfoFromStylesheet(cssString)],
-    varUsedByTraceId: new Map(),
+    css: cssStrings.map(cssInfoFromStylesheet),
+    varUsedByTraceId: new Map(
+      Object.keys(matchedCustomProperties).map((varName) => [varName, new Set(['trace-root'])]),
+    ),
   }
 }
 
+function createComponentWithCss(cssString: string): ComponentInfoWithCss {
+  return { ...createComponentWithStylesheets([cssString]), componentName: 'PropertyTokens' }
+}
+
 describe('toEditorReactComponent — @property design tokens', () => {
   it('emits typed cssCustomProperties from @property, defaulting from initial-value with no element declaration', () => {
     const component = createComponentWithCss(`
@@ -652,3 +701,64 @@ describe('toEditorReactComponent — ActiveItemIndex display groups', () => {
     expect(editorElement?.data?.activeTab?.dataType).toBe('number')
   })
 })
+
+describe('toEditorReactComponent — custom property typing across several stylesheets', () => {
+  const packageStylesheet = '@property --sdf-intensity { syntax: "<number>"; inherits: false; initial-value: 1; }'
+  const componentStylesheet = '.card { --sdf-intensity: 1; background-color: var(--sdf-intensity); }'
+
+  it('collects a @property registration from any stylesheet, whichever order they arrive in', () => {
+    for (const stylesheets of [
+      [componentStylesheet, packageStylesheet],
+      [packageStylesheet, componentStylesheet],
+    ]) {
+      const customProps = toEditorReactComponent(createComponentWithStylesheets(stylesheets)).editorElement
+        ?.cssCustomProperties
+
+      // Usage alone infers 'backgroundColor'.
+      expect(customProps?.['sdf-intensity']?.cssPropertyType).toBe('number')
+    }
+  })
+
+  it('ignores a stylesheet that never mentions the variable, either order', () => {
+    const unrelatedStylesheet = '.a { font: var(--wst-heading-1-font); }'
+    const owningStylesheet = '.b { --accent: 4px; padding: var(--accent); }'
+
+    for (const stylesheets of [
+      [unrelatedStylesheet, owningStylesheet],
+      [owningStylesheet, unrelatedStylesheet],
+    ]) {
+      const customProps = toEditorReactComponent(createComponentWithStylesheets(stylesheets, { '--accent': '4px' }))
+        .editorElement?.cssCustomProperties
+
+      // Guessing from the '4px' default alone infers 'length'.
+      expect(customProps?.accent?.cssPropertyType).toBe('padding')
+    }
+  })
+
+  it('attributes a variable from the union of its usages, however they are split up', () => {
+    // Splitting a stylesheet in two must not make attribution more confident: one stylesheet
+    // using --accent in both `color` and `padding` cannot attribute it, and neither can two.
+    const together = ['.a { --accent: 4px; color: var(--accent); padding: var(--accent); }']
+    const splitFirst = '.a { --accent: 4px; color: var(--accent); }'
+    const splitSecond = '.b { padding: var(--accent); }'
+
+    for (const stylesheets of [together, [splitFirst, splitSecond], [splitSecond, splitFirst]]) {
+      const customProps = toEditorReactComponent(createComponentWithStylesheets(stylesheets, { '--accent': '4px' }))
+        .editorElement?.cssCustomProperties
+
+      expect(customProps?.accent?.cssPropertyType).toBe('length')
+    }
+  })
+
+  it('does not let an unrelated stylesheet type a variable from the default value alone', () => {
+    const unrelatedStylesheet = '.wst-heading-1 { font: var(--wst-heading-1-font); }'
+    const owningStylesheet = '.card { --background-color: #ffffff; background-color: var(--background-color); }'
+
+    const customProps = toEditorReactComponent(
+      createComponentWithStylesheets([unrelatedStylesheet, owningStylesheet], { '--background-color': '#ffffff' }),
+    ).editorElement?.cssCustomProperties
+
+    // Guessing from the '#ffffff' default alone infers 'color'.
+    expect(customProps?.['background-color']?.cssPropertyType).toBe('backgroundColor')
+  })
+})

package/src/converters/to-editor-component.ts

@@ -10,13 +10,13 @@ import type {
   ElementItem,
   States,
 } from '@wix/react-component-schema'
-import { CSS_PROPERTIES, ELEMENTS } from '@wix/react-component-schema'
+import { CSS_PROPERTIES, DATA, ELEMENTS } from '@wix/react-component-schema'
 import { camelCase } from 'case-anything'
 import { IoError } from '../errors'
 import { buildRefElementManifestKey } from '../extensions/ref-elements/path-utils'
 import type { RefElementMatch } from '../extensions/ref-elements/types'
 import type { ComponentInfoWithCss } from '../index'
-import { stripVarFallback } from '../information-extractors/css/parse'
+import { cssPropertyTypeFromUsages, inferCssDataType, stripVarFallback } from '../information-extractors/css/parse'
 import type { MatchedCssData, RegisteredCustomProperty } from '../information-extractors/css/types'
 import type {
   CoupledComponentInfo,
@@ -184,6 +184,7 @@ function buildData(
 
     const result = buildDataItem(prop, defaultValue, propUsages, prop.propPath)
     if (result.isErr()) throw result.error
+    if (result.value.dataType === DATA.DATA_TYPE.a11y && !result.value.a11y?.attributes?.length) continue
     // ActiveItemIndex props default to 0 when no default is specified
     if (prop.activeItemIndexTarget && result.value.defaultValue === undefined) {
       result.value.defaultValue = 0
@@ -414,20 +415,15 @@ function buildCssNumber(
   }
 }
 
-/**
- * Queries each CSS parser API for the property type of a variable and returns
- * the first defined result.
- */
 function getVarPropertyTypeFromCssInfos(
   varName: string,
   defaultValue: string,
   cssInfos: ComponentInfoWithCss['css'],
 ): CssCustomPropertyItem['cssPropertyType'] {
-  for (const cssInfo of cssInfos) {
-    const propertyType = cssInfo.api.getVarPropertyType(varName, defaultValue)
-    if (propertyType !== undefined) return propertyType as CssCustomPropertyItem['cssPropertyType']
-  }
-  return undefined
+  const usagesAcrossStylesheets = cssInfos.flatMap((cssInfo) => cssInfo.api.getVarUsages(varName))
+
+  return (cssPropertyTypeFromUsages(usagesAcrossStylesheets) ??
+    inferCssDataType(defaultValue)) as CssCustomPropertyItem['cssPropertyType']
 }
 
 /**

package/src/information-extractors/css/parse.test.ts

@@ -216,7 +216,23 @@ describe('parseCss — @property registration', () => {
 
     // Used only in background-color, which would otherwise infer 'backgroundColor';
     // the @property declaration wins.
-    expect(api.getVarPropertyType('--sdf-intensity', '1')).toBe('number')
+    expect(api.getVarPropertyType('--sdf-intensity')).toBe('number')
+  })
+
+  it('says nothing about a variable it cannot attribute to a single known property', () => {
+    const unrelatedApi = parseCss('.wst-heading-1 { color: var(--wst-heading-1-color); }')
+
+    expect(unrelatedApi.getVarPropertyType('--background-color')).toBeUndefined()
+
+    const owningApi = parseCss('.card { --background-color: #ffffff; background-color: var(--background-color); }')
+
+    expect(owningApi.getVarPropertyType('--background-color')).toBe('backgroundColor')
+
+    const ambiguousApi = parseCss('.card { z-index: var(--background-color); opacity: var(--background-color); }')
+    const unmodelledApi = parseCss('.card { grid-template-columns: var(--background-color); }')
+
+    expect(ambiguousApi.getVarPropertyType('--background-color')).toBeUndefined()
+    expect(unmodelledApi.getVarPropertyType('--background-color')).toBeUndefined()
   })
 })
 

package/src/information-extractors/css/parse.ts

@@ -85,21 +85,13 @@ export function parseCss(cssString: string): CSSParserAPI {
       return getSelectorSpecificity(parsed)
     },
 
-    getVarPropertyType(varName: string, defaultValue: string): string {
+    getVarPropertyType(varName: string): string | undefined {
       // A `@property` registration is the declared type and wins over usage inference.
       const normalizedVarName = varName.startsWith('--') ? varName : `--${varName}`
       const registered = registeredProperties.get(normalizedVarName)
       if (registered) return registered.cssPropertyType
 
-      const usages = this.getVarUsages(varName)
-      if (usages.length === 0) return inferCssDataType(defaultValue)
-      const uniqueProperties = [...new Set(usages)]
-      if (uniqueProperties.length === 1) {
-        const camelCased = camelCase(uniqueProperties[0])
-        const validValues = Object.values(CSS_PROPERTIES.CSS_PROPERTY_TYPE) as string[]
-        if (validValues.includes(camelCased)) return camelCased
-      }
-      return inferCssDataType(defaultValue)
+      return cssPropertyTypeFromUsages(this.getVarUsages(varName))
     },
 
     getRegisteredCustomProperties(): Map<string, RegisteredCustomProperty> {
@@ -825,12 +817,28 @@ function matchesCssType(typeName: string, value: CssNode): boolean {
   return !lexer.matchType(typeName, value).error
 }
 
+/**
+ * The manifest `cssPropertyType` a set of `var()` usages attributes to a custom property:
+ * the property name itself when every usage sits in one known CSS property, otherwise
+ * undefined. Callers holding several stylesheets must pass the union of their usages — a
+ * variable spread across two stylesheets is no more attributable than one spread across two
+ * rules of the same stylesheet.
+ */
+export function cssPropertyTypeFromUsages(propertyNames: Iterable<string>): string | undefined {
+  const uniqueProperties = [...new Set(propertyNames)]
+  if (uniqueProperties.length !== 1) return undefined
+
+  const camelCasedProperty = camelCase(uniqueProperties[0])
+  const propertyTypes = Object.values(CSS_PROPERTIES.CSS_PROPERTY_TYPE) as string[]
+  return propertyTypes.includes(camelCasedProperty) ? camelCasedProperty : undefined
+}
+
 /**
  * Infers the CSS data type category from a custom property's initial value string.
  * Uses css-tree's lexer to match the value against known CSS types.
  * Returns a value from CSS_PROPERTIES.CSS_DATA_TYPE.
  */
-function inferCssDataType(defaultValue: string): string {
+export function inferCssDataType(defaultValue: string): string {
   const { CSS_DATA_TYPE } = CSS_PROPERTIES
 
   try {

package/src/information-extractors/css/types.ts

@@ -134,16 +134,16 @@ export interface CSSParserAPI {
   getSelectorSpecificity: (selector: string) => [number, number, number] | null
 
   /**
-   * Determines the CSS property type for a custom property.
-   * A `@property` registration is the top-priority source (declared type). Otherwise
-   * falls back to usage: if all usages of varName are within the same CSS property,
-   * returns that property name; if usages differ, or if the variable is not used via
-   * var() at all, returns the CSS data type inferred from the initial value
-   * ('color', 'length', 'number', or 'string').
+   * Determines the CSS property type this one stylesheet can attribute to a custom property.
+   * A `@property` registration is the top-priority source (declared type). Otherwise falls back
+   * to usage: if every usage of varName is within the same known CSS property, returns that
+   * property name. Returns undefined when this stylesheet cannot attribute one — it does not
+   * mention the variable, spreads it across several properties, or uses it in a property with
+   * no manifest type. Callers holding several stylesheets ask the next one, and are responsible
+   * for the final fallback when none can answer.
    * @param varName - The CSS variable name (with or without --)
-   * @param defaultValue - The initial value string of the custom property
    */
-  getVarPropertyType: (varName: string, defaultValue: string) => string
+  getVarPropertyType: (varName: string) => string | undefined
 
   /**
    * Returns every custom property registered via a `@property` at-rule, keyed by the

package/src/information-extractors/ts/css-imports.test.ts

@@ -0,0 +1,177 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import ts from 'typescript'
+import { afterEach, describe, expect, it } from 'vitest'
+import { NotFoundError } from '../../errors'
+import { extractCssImports } from './css-imports'
+
+const temporaryDirectoryPaths: string[] = []
+
+afterEach(() => {
+  for (const temporaryDirectoryPath of temporaryDirectoryPaths.splice(0)) {
+    fs.rmSync(temporaryDirectoryPath, { force: true, recursive: true })
+  }
+})
+
+function createConsumerProject(componentSource: string): { componentPath: string } {
+  // Node resolution reports realpaths, which on macOS differ from the `/var/...` mkdtemp returns.
+  const temporaryDirectoryPath = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'zero-config-css-imports-')))
+  temporaryDirectoryPaths.push(temporaryDirectoryPath)
+
+  const stylesPackagePath = path.join(temporaryDirectoryPath, 'node_modules', '@fixture', 'site-ui')
+  fs.mkdirSync(path.join(stylesPackagePath, 'dist', 'Typography'), { recursive: true })
+  fs.writeFileSync(
+    path.join(stylesPackagePath, 'package.json'),
+    JSON.stringify({
+      name: '@fixture/site-ui',
+      version: '1.0.0',
+      type: 'module',
+      exports: { './*.css': './dist/*/index.css', './*.scss': './dist/*/index.scss' },
+    }),
+  )
+  fs.writeFileSync(path.join(stylesPackagePath, 'dist', 'Typography', 'index.css'), '.title { color: red; }\n')
+  fs.writeFileSync(path.join(stylesPackagePath, 'dist', 'Typography', 'index.scss'), '.title { color: red; }\n')
+
+  const plainPackagePath = path.join(temporaryDirectoryPath, 'node_modules', 'plain-styles')
+  fs.mkdirSync(path.join(plainPackagePath, 'dist'), { recursive: true })
+  fs.writeFileSync(
+    path.join(plainPackagePath, 'package.json'),
+    JSON.stringify({ name: 'plain-styles', version: '1.0.0', main: 'index.js' }),
+  )
+  fs.writeFileSync(path.join(plainPackagePath, 'dist', 'theme.css'), '.plain { color: green; }\n')
+  fs.mkdirSync(path.join(plainPackagePath, 'dist', 'directory.css'), { recursive: true })
+
+  const linkedPackagePath = path.join(temporaryDirectoryPath, 'packages', 'linked-styles')
+  fs.mkdirSync(linkedPackagePath, { recursive: true })
+  fs.writeFileSync(
+    path.join(linkedPackagePath, 'package.json'),
+    JSON.stringify({ name: 'linked-styles', version: '1.0.0', exports: { './theme.css': './theme.css' } }),
+  )
+  fs.writeFileSync(path.join(linkedPackagePath, 'theme.css'), '.linked { color: teal; }\n')
+  fs.symlinkSync(linkedPackagePath, path.join(temporaryDirectoryPath, 'node_modules', 'linked-styles'), 'dir')
+
+  const componentDirectoryPath = path.join(temporaryDirectoryPath, 'src', 'components', 'heading')
+  fs.mkdirSync(componentDirectoryPath, { recursive: true })
+  fs.writeFileSync(path.join(componentDirectoryPath, 'local.css'), '.local { color: blue; }\n')
+
+  const componentPath = path.join(componentDirectoryPath, 'component.tsx')
+  fs.writeFileSync(componentPath, componentSource)
+
+  return { componentPath }
+}
+
+function createProgram(componentPath: string): ts.Program {
+  return ts.createProgram([componentPath], {
+    jsx: ts.JsxEmit.ReactJSX,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    noResolve: true,
+    target: ts.ScriptTarget.ESNext,
+  })
+}
+
+describe('extractCssImports — stylesheet specifier resolution', () => {
+  it('resolves a bare stylesheet specifier through the package exports map', () => {
+    const { componentPath } = createConsumerProject(
+      ["import '@fixture/site-ui/Typography.css'", 'export default function Heading() {', '  return null', '}'].join(
+        '\n',
+      ),
+    )
+
+    const cssImportPaths = extractCssImports(createProgram(componentPath))
+
+    const packageRootPath = path.resolve(path.dirname(componentPath), '../../../node_modules/@fixture/site-ui')
+    expect(cssImportPaths).toEqual([path.join(packageRootPath, 'dist', 'Typography', 'index.css')])
+  })
+
+  it('still resolves relative stylesheet specifiers against the importing file', () => {
+    const { componentPath } = createConsumerProject(
+      ["import './local.css'", 'export default function Heading() {', '  return null', '}'].join('\n'),
+    )
+
+    const cssImportPaths = extractCssImports(createProgram(componentPath))
+
+    expect(cssImportPaths).toEqual([path.join(path.dirname(componentPath), 'local.css')])
+  })
+
+  it('resolves a bare specifier from a package that publishes no exports map', () => {
+    const { componentPath } = createConsumerProject(
+      ["import 'plain-styles/dist/theme.css'", 'export default function Heading() {', '  return null', '}'].join('\n'),
+    )
+
+    const cssImportPaths = extractCssImports(createProgram(componentPath))
+
+    const packageRootPath = path.resolve(path.dirname(componentPath), '../../../node_modules/plain-styles')
+    expect(cssImportPaths).toEqual([path.join(packageRootPath, 'dist', 'theme.css')])
+  })
+
+  it('resolves a bare sass specifier through the package exports map', () => {
+    const { componentPath } = createConsumerProject(
+      ["import '@fixture/site-ui/Typography.scss'", 'export default function Heading() {', '  return null', '}'].join(
+        '\n',
+      ),
+    )
+
+    const cssImportPaths = extractCssImports(createProgram(componentPath))
+
+    expect(cssImportPaths[0]).toMatch(/site-ui[\\/]dist[\\/]Typography[\\/]index\.scss$/)
+  })
+
+  it('throws when a package without an exports map has no file at the specified subpath', () => {
+    // Node skips the exports algorithm entirely for such packages, so resolution reports a path
+    // whether or not a file is there.
+    const { componentPath } = createConsumerProject(
+      ["import 'plain-styles/dist/missing.css'", 'export default function Heading() {', '  return null', '}'].join(
+        '\n',
+      ),
+    )
+
+    expect(() => extractCssImports(createProgram(componentPath))).toThrow(/which is not a file/)
+  })
+
+  it('throws when the resolved path is a directory rather than a stylesheet', () => {
+    const { componentPath } = createConsumerProject(
+      ["import 'plain-styles/dist/directory.css'", 'export default function Heading() {', '  return null', '}'].join(
+        '\n',
+      ),
+    )
+
+    expect(() => extractCssImports(createProgram(componentPath))).toThrow(/which is not a file/)
+  })
+
+  it('emits one entry for a linked package stylesheet reached both bare and relatively', () => {
+    const { componentPath } = createConsumerProject(
+      [
+        "import 'linked-styles/theme.css'",
+        "import '../../../node_modules/linked-styles/theme.css'",
+        'export default function Heading() {',
+        '  return null',
+        '}',
+      ].join('\n'),
+    )
+
+    const cssImportPaths = extractCssImports(createProgram(componentPath))
+
+    const linkedPackagePath = path.resolve(path.dirname(componentPath), '../../../packages/linked-styles')
+    expect(cssImportPaths).toEqual([path.join(linkedPackagePath, 'theme.css')])
+  })
+
+  it('throws a descriptive error when a bare stylesheet specifier cannot be resolved', () => {
+    const { componentPath } = createConsumerProject(
+      [
+        "import '@fixture/not-installed/Typography.css'",
+        'export default function Heading() {',
+        '  return null',
+        '}',
+      ].join('\n'),
+    )
+
+    const program = createProgram(componentPath)
+
+    expect(() => extractCssImports(program)).toThrow(
+      /Cannot resolve stylesheet import "@fixture\/not-installed\/Typography\.css"/,
+    )
+    expect(() => extractCssImports(createProgram(componentPath))).toThrow(NotFoundError)
+  })
+})

package/src/information-extractors/ts/css-imports.ts

@@ -1,7 +1,62 @@
+import * as fs from 'node:fs'
 import * as path from 'node:path'
 import ts, { type Program } from 'typescript'
+import { NotFoundError } from '../../errors'
+import { resolveModulePathFromEntryPath } from '../../extensions/shared/module-resolution'
 
 const MAX_DEPTH = 100
+const STYLESHEET_EXTENSIONS = ['.css', '.scss', '.sass']
+
+function isStylesheetSpecifier(importPath: string): boolean {
+  return STYLESHEET_EXTENSIONS.some((extension) => importPath.endsWith(extension))
+}
+
+function isPathSpecifier(importPath: string): boolean {
+  return importPath.startsWith('./') || importPath.startsWith('../') || path.isAbsolute(importPath)
+}
+
+function isFile(filePath: string): boolean {
+  try {
+    return fs.statSync(filePath).isFile()
+  } catch {
+    return false
+  }
+}
+
+// Node resolution reports realpaths, so path specifiers must be normalised the same way for
+// `cssFiles` to dedupe a stylesheet reached both ways.
+function toRealPath(filePath: string): string {
+  try {
+    return fs.realpathSync(filePath)
+  } catch {
+    return filePath
+  }
+}
+
+function resolveStylesheetPath(importPath: string, importingFileName: string): string {
+  if (isPathSpecifier(importPath)) {
+    return toRealPath(path.resolve(path.dirname(importingFileName), importPath))
+  }
+
+  const packageResolvedPath = resolveModulePathFromEntryPath(importingFileName, importPath)
+  if (!packageResolvedPath) {
+    throw new NotFoundError(
+      `Cannot resolve stylesheet import "${importPath}" from "${importingFileName}". Ensure the package is installed and that its "exports" map covers this subpath.`,
+      { props: { phase: 'css' } },
+    )
+  }
+
+  // A package with no `exports` map resolves by plain path join, so Node reports a path whether
+  // or not a file is there. Reading it is the only thing that settles it.
+  if (!isFile(packageResolvedPath)) {
+    throw new NotFoundError(
+      `Stylesheet import "${importPath}" from "${importingFileName}" resolves to "${packageResolvedPath}", which is not a file.`,
+      { props: { phase: 'css' } },
+    )
+  }
+
+  return toRealPath(packageResolvedPath)
+}
 
 export function extractCssImports(program: Program): string[] {
   const cssFiles = new Set<string>()
@@ -16,9 +71,8 @@ export function extractCssImports(program: Program): string[] {
       if (!ts.isImportDeclaration(node) || !ts.isStringLiteral(node.moduleSpecifier)) return
       const importPath = node.moduleSpecifier.text
 
-      if (importPath.endsWith('.css') || importPath.endsWith('.scss') || importPath.endsWith('.sass')) {
-        const fullPath = path.resolve(path.dirname(sourceFile.fileName), importPath)
-        cssFiles.add(fullPath)
+      if (isStylesheetSpecifier(importPath)) {
+        cssFiles.add(resolveStylesheetPath(importPath, sourceFile.fileName))
         return
       }