postcss 8.3.9 → 8.4.31

package/lib/input.d.ts

@@ -1,31 +1,46 @@
-import { ProcessOptions } from './postcss.js'
+import { CssSyntaxError, ProcessOptions } from './postcss.js'
 import PreviousMap from './previous-map.js'
 
-export interface FilePosition {
-  /**
-   * URL for the source file.
-   */
-  url: string
+declare namespace Input {
+  export interface FilePosition {
+    /**
+     * Column of inclusive start position in source file.
+     */
+    column: number
 
-  /**
-   * Absolute path to the source file.
-   */
-  file?: string
+    /**
+     * Column of exclusive end position in source file.
+     */
+    endColumn?: number
 
-  /**
-   * Line in source file.
-   */
-  line: number
+    /**
+     * Line of exclusive end position in source file.
+     */
+    endLine?: number
 
-  /**
-   * Column in source file.
-   */
-  column: number
+    /**
+     * Absolute path to the source file.
+     */
+    file?: string
 
-  /**
-   * Source code.
-   */
-  source?: string
+    /**
+     * Line of inclusive start position in source file.
+     */
+    line: number
+
+    /**
+     * Source code.
+     */
+    source?: string
+
+    /**
+     * URL for the source file.
+     */
+    url: string
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-use-before-define
+  export { Input_ as default }
 }
 
 /**
@@ -36,7 +51,7 @@ export interface FilePosition {
  * const input = root.source.input
  * ```
  */
-export default class Input {
+declare class Input_ {
   /**
    * Input CSS source.
    *
@@ -47,16 +62,6 @@ export default class Input {
    */
   css: string
 
-  /**
-   * The input source map passed from a compilation step before PostCSS
-   * (for example, from Sass compiler).
-   *
-   * ```js
-   * root.source.input.map.consumer().sources //=> ['a.sass']
-   * ```
-   */
-  map: PreviousMap
-
   /**
    * The absolute path to the CSS source file defined
    * with the `from` option.
@@ -68,6 +73,11 @@ export default class Input {
    */
   file?: string
 
+  /**
+   * The flag to indicate whether or not the source code has Unicode BOM.
+   */
+  hasBOM: boolean
+
   /**
    * The unique ID of the CSS source. It will be created if `from` option
    * is not provided (because PostCSS does not know the file path).
@@ -81,9 +91,14 @@ export default class Input {
   id?: string
 
   /**
-   * The flag to indicate whether or not the source code has Unicode BOM.
+   * The input source map passed from a compilation step before PostCSS
+   * (for example, from Sass compiler).
+   *
+   * ```js
+   * root.source.input.map.consumer().sources //=> ['a.sass']
+   * ```
    */
-  hasBOM: boolean
+  map: PreviousMap
 
   /**
    * @param css  Input CSS source.
@@ -91,40 +106,89 @@ export default class Input {
    */
   constructor(css: string, opts?: ProcessOptions)
 
+  error(
+    message: string,
+    start:
+      | {
+          column: number
+          line: number
+        }
+      | {
+          offset: number
+        },
+    end:
+      | {
+          column: number
+          line: number
+        }
+      | {
+          offset: number
+        },
+    opts?: { plugin?: CssSyntaxError['plugin'] }
+  ): CssSyntaxError
+
   /**
-   * The CSS source identifier. Contains `Input#file` if the user
-   * set the `from` option, or `Input#id` if they did not.
-   *
-   * ```js
-   * const root = postcss.parse(css, { from: 'a.css' })
-   * root.source.input.from //=> "/home/ai/a.css"
-   *
-   * const root = postcss.parse(css)
-   * root.source.input.from //=> "<input css 1>"
-   * ```
+   * Returns `CssSyntaxError` with information about the error and its position.
    */
-  get from(): string
+  error(
+    message: string,
+    line: number,
+    column: number,
+    opts?: { plugin?: CssSyntaxError['plugin'] }
+  ): CssSyntaxError
+
+  error(
+    message: string,
+    offset: number,
+    opts?: { plugin?: CssSyntaxError['plugin'] }
+  ): CssSyntaxError
 
+  /**
+   * Converts source offset to line and column.
+   *
+   * @param offset Source offset.
+   */
+  fromOffset(offset: number): { col: number; line: number } | null
   /**
    * Reads the input source map and returns a symbol position
    * in the input source (e.g., in a Sass file that was compiled
-   * to CSS before being passed to PostCSS).
+   * to CSS before being passed to PostCSS). Optionally takes an
+   * end position, exclusive.
    *
    * ```js
    * root.source.input.origin(1, 1) //=> { file: 'a.css', line: 3, column: 1 }
+   * root.source.input.origin(1, 1, 1, 4)
+   * //=> { file: 'a.css', line: 3, column: 1, endLine: 3, endColumn: 4 }
    * ```
    *
-   * @param line   Line in input CSS.
-   * @param column Column in input CSS.
+   * @param line      Line for inclusive start position in input CSS.
+   * @param column    Column for inclusive start position in input CSS.
+   * @param endLine   Line for exclusive end position in input CSS.
+   * @param endColumn Column for exclusive end position in input CSS.
    *
    * @return Position in input source.
    */
-  origin(line: number, column: number): FilePosition | false
-
+  origin(
+    line: number,
+    column: number,
+    endLine?: number,
+    endColumn?: number
+  ): false | Input.FilePosition
   /**
-   * Converts source offset to line and column.
+   * The CSS source identifier. Contains `Input#file` if the user
+   * set the `from` option, or `Input#id` if they did not.
    *
-   * @param offset Source offset.
+   * ```js
+   * const root = postcss.parse(css, { from: 'a.css' })
+   * root.source.input.from //=> "/home/ai/a.css"
+   *
+   * const root = postcss.parse(css)
+   * root.source.input.from //=> "<input css 1>"
+   * ```
    */
-  fromOffset(offset: number): { line: number; col: number } | null
+  get from(): string
 }
+
+declare class Input extends Input_ {}
+
+export = Input

package/lib/input.js

@@ -2,7 +2,7 @@
 
 let { SourceMapConsumer, SourceMapGenerator } = require('source-map-js')
 let { fileURLToPath, pathToFileURL } = require('url')
-let { resolve, isAbsolute } = require('path')
+let { isAbsolute, resolve } = require('path')
 let { nanoid } = require('nanoid/non-secure')
 
 let terminalHighlight = require('./terminal-highlight')
@@ -60,6 +60,70 @@ class Input {
     if (this.map) this.map.file = this.from
   }
 
+  error(message, line, column, opts = {}) {
+    let result, endLine, endColumn
+
+    if (line && typeof line === 'object') {
+      let start = line
+      let end = column
+      if (typeof start.offset === 'number') {
+        let pos = this.fromOffset(start.offset)
+        line = pos.line
+        column = pos.col
+      } else {
+        line = start.line
+        column = start.column
+      }
+      if (typeof end.offset === 'number') {
+        let pos = this.fromOffset(end.offset)
+        endLine = pos.line
+        endColumn = pos.col
+      } else {
+        endLine = end.line
+        endColumn = end.column
+      }
+    } else if (!column) {
+      let pos = this.fromOffset(line)
+      line = pos.line
+      column = pos.col
+    }
+
+    let origin = this.origin(line, column, endLine, endColumn)
+    if (origin) {
+      result = new CssSyntaxError(
+        message,
+        origin.endLine === undefined
+          ? origin.line
+          : { column: origin.column, line: origin.line },
+        origin.endLine === undefined
+          ? origin.column
+          : { column: origin.endColumn, line: origin.endLine },
+        origin.source,
+        origin.file,
+        opts.plugin
+      )
+    } else {
+      result = new CssSyntaxError(
+        message,
+        endLine === undefined ? line : { column, line },
+        endLine === undefined ? column : { column: endColumn, line: endLine },
+        this.css,
+        this.file,
+        opts.plugin
+      )
+    }
+
+    result.input = { column, endColumn, endLine, line, source: this.css }
+    if (this.file) {
+      if (pathToFileURL) {
+        result.input.url = pathToFileURL(this.file).toString()
+      }
+      result.input.file = this.file
+    }
+
+    return result
+  }
+
   fromOffset(offset) {
     let lastLine, lineToIndex
     if (!this[fromOffsetCache]) {
@@ -97,57 +161,30 @@ class Input {
       }
     }
     return {
-      line: min + 1,
-      col: offset - lineToIndex[min] + 1
+      col: offset - lineToIndex[min] + 1,
+      line: min + 1
     }
   }
 
-  error(message, line, column, opts = {}) {
-    let result
-    if (!column) {
-      let pos = this.fromOffset(line)
-      line = pos.line
-      column = pos.col
-    }
-    let origin = this.origin(line, column)
-    if (origin) {
-      result = new CssSyntaxError(
-        message,
-        origin.line,
-        origin.column,
-        origin.source,
-        origin.file,
-        opts.plugin
-      )
-    } else {
-      result = new CssSyntaxError(
-        message,
-        line,
-        column,
-        this.css,
-        this.file,
-        opts.plugin
-      )
-    }
-
-    result.input = { line, column, source: this.css }
-    if (this.file) {
-      if (pathToFileURL) {
-        result.input.url = pathToFileURL(this.file).toString()
-      }
-      result.input.file = this.file
+  mapResolve(file) {
+    if (/^\w+:\/\//.test(file)) {
+      return file
     }
-
-    return result
+    return resolve(this.map.consumer().sourceRoot || this.map.root || '.', file)
   }
 
-  origin(line, column) {
+  origin(line, column, endLine, endColumn) {
     if (!this.map) return false
     let consumer = this.map.consumer()
 
-    let from = consumer.originalPositionFor({ line, column })
+    let from = consumer.originalPositionFor({ column, line })
     if (!from.source) return false
 
+    let to
+    if (typeof endLine === 'number') {
+      to = consumer.originalPositionFor({ column: endColumn, line: endLine })
+    }
+
     let fromUrl
 
     if (isAbsolute(from.source)) {
@@ -160,16 +197,18 @@ class Input {
     }
 
     let result = {
-      url: fromUrl.toString(),
+      column: from.column,
+      endColumn: to && to.column,
+      endLine: to && to.line,
       line: from.line,
-      column: from.column
+      url: fromUrl.toString()
     }
 
     if (fromUrl.protocol === 'file:') {
       if (fileURLToPath) {
         result.file = fileURLToPath(fromUrl)
       } else {
-        // istanbul ignore next
+        /* c8 ignore next 2 */
         throw new Error(`file: protocol is not available in this PostCSS build`)
       }
     }
@@ -180,17 +219,6 @@ class Input {
     return result
   }
 
-  mapResolve(file) {
-    if (/^\w+:\/\//.test(file)) {
-      return file
-    }
-    return resolve(this.map.consumer().sourceRoot || this.map.root || '.', file)
-  }
-
-  get from() {
-    return this.file || this.id
-  }
-
   toJSON() {
     let json = {}
     for (let name of ['hasBOM', 'css', 'file', 'id']) {
@@ -206,6 +234,10 @@ class Input {
     }
     return json
   }
+
+  get from() {
+    return this.file || this.id
+  }
 }
 
 module.exports = Input

package/lib/lazy-result.d.ts

@@ -1,8 +1,14 @@
-import Result, { Message, ResultOptions } from './result.js'
+import Document from './document.js'
 import { SourceMap } from './postcss.js'
 import Processor from './processor.js'
-import Warning from './warning.js'
+import Result, { Message, ResultOptions } from './result.js'
 import Root from './root.js'
+import Warning from './warning.js'
+
+declare namespace LazyResult {
+  // eslint-disable-next-line @typescript-eslint/no-use-before-define
+  export { LazyResult_ as default }
+}
 
 /**
  * A Promise proxy for the result of PostCSS transformations.
@@ -13,51 +19,53 @@ import Root from './root.js'
  * const lazy = postcss([autoprefixer]).process(css)
  * ```
  */
-export default class LazyResult implements PromiseLike<Result> {
+declare class LazyResult_<RootNode = Document | Root>
+  implements PromiseLike<Result<RootNode>>
+{
   /**
    * Processes input CSS through synchronous and asynchronous plugins
-   * and calls `onFulfilled` with a Result instance. If a plugin throws
-   * an error, the `onRejected` callback will be executed.
+   * and calls onRejected for each error thrown in any plugin.
    *
    * It implements standard Promise API.
    *
    * ```js
-   * postcss([autoprefixer]).process(css, { from: cssPath }).then(result => {
+   * postcss([autoprefixer]).process(css).then(result => {
    *   console.log(result.css)
+   * }).catch(error => {
+   *   console.error(error)
    * })
    * ```
    */
-  then: Promise<Result>['then']
+  catch: Promise<Result<RootNode>>['catch']
 
   /**
    * Processes input CSS through synchronous and asynchronous plugins
-   * and calls onRejected for each error thrown in any plugin.
+   * and calls onFinally on any error or when all plugins will finish work.
    *
    * It implements standard Promise API.
    *
    * ```js
-   * postcss([autoprefixer]).process(css).then(result => {
-   *   console.log(result.css)
-   * }).catch(error => {
-   *   console.error(error)
+   * postcss([autoprefixer]).process(css).finally(() => {
+   *   console.log('processing ended')
    * })
    * ```
    */
-  catch: Promise<Result>['catch']
+  finally: Promise<Result<RootNode>>['finally']
 
   /**
    * Processes input CSS through synchronous and asynchronous plugins
-   * and calls onFinally on any error or when all plugins will finish work.
+   * and calls `onFulfilled` with a Result instance. If a plugin throws
+   * an error, the `onRejected` callback will be executed.
    *
    * It implements standard Promise API.
    *
    * ```js
-   * postcss([autoprefixer]).process(css).finally(() => {
-   *   console.log('processing ended')
+   * postcss([autoprefixer]).process(css, { from: cssPath }).then(result => {
+   *   console.log(result.css)
    * })
    * ```
    */
-  finally: Promise<Result>['finally']
+  then: Promise<Result<RootNode>>['then']
 
   /**
    * @param processor Processor used for this transformation.
@@ -67,32 +75,37 @@ export default class LazyResult implements PromiseLike<Result> {
   constructor(processor: Processor, css: string, opts: ResultOptions)
 
   /**
-   * Returns the default string description of an object.
-   * Required to implement the Promise interface.
+   * Run plugin in async way and return `Result`.
+   *
+   * @return Result with output content.
    */
-  get [Symbol.toStringTag](): string
+  async(): Promise<Result<RootNode>>
 
   /**
-   * Returns a `Processor` instance, which will be used
-   * for CSS transformations.
+   * Run plugin in sync way and return `Result`.
+   *
+   * @return Result with output content.
    */
-  get processor(): Processor
+  sync(): Result<RootNode>
 
   /**
-   * Options from the `Processor#process` call.
+   * Alias for the `LazyResult#css` property.
+   *
+   * ```js
+   * lazy + '' === lazy.css
+   * ```
+   *
+   * @return Output CSS.
    */
-  get opts(): ResultOptions
+  toString(): string
 
   /**
-   * Processes input CSS through synchronous plugins, converts `Root`
-   * to a CSS string and returns `Result#css`.
+   * Processes input CSS through synchronous plugins
+   * and calls `Result#warnings`.
    *
-   * This property will only work with synchronous plugins.
-   * If the processor contains any asynchronous plugins
-   * it will throw an error. This is why this method is only
-   * for debug purpose, you should always use `LazyResult#then`.
+   * @return Warnings from plugins.
    */
-  get css(): string
+  warnings(): Warning[]
 
   /**
    * An alias for the `css` property. Use it with syntaxes
@@ -100,33 +113,35 @@ export default class LazyResult implements PromiseLike<Result> {
    *
    * This property will only work with synchronous plugins.
    * If the processor contains any asynchronous plugins
-   * it will throw an error. This is why this method is only
-   * for debug purpose, you should always use `LazyResult#then`.
+   * it will throw an error.
+   *
+   * PostCSS runners should always use `LazyResult#then`.
    */
   get content(): string
 
   /**
-   * Processes input CSS through synchronous plugins
-   * and returns `Result#map`.
+   * Processes input CSS through synchronous plugins, converts `Root`
+   * to a CSS string and returns `Result#css`.
    *
    * This property will only work with synchronous plugins.
    * If the processor contains any asynchronous plugins
-   * it will throw an error. This is why this method is only
-   * for debug purpose, you should always use `LazyResult#then`.
+   * it will throw an error.
+   *
+   * PostCSS runners should always use `LazyResult#then`.
    */
-  get map(): SourceMap
+  get css(): string
 
   /**
    * Processes input CSS through synchronous plugins
-   * and returns `Result#root`.
+   * and returns `Result#map`.
    *
-   * This property will only work with synchronous plugins. If the processor
-   * contains any asynchronous plugins it will throw an error.
+   * This property will only work with synchronous plugins.
+   * If the processor contains any asynchronous plugins
+   * it will throw an error.
    *
-   * This is why this method is only for debug purpose,
-   * you should always use `LazyResult#then`.
+   * PostCSS runners should always use `LazyResult#then`.
    */
-  get root(): Root
+  get map(): SourceMap
 
   /**
    * Processes input CSS through synchronous plugins
@@ -135,41 +150,41 @@ export default class LazyResult implements PromiseLike<Result> {
    * This property will only work with synchronous plugins. If the processor
    * contains any asynchronous plugins it will throw an error.
    *
-   * This is why this method is only for debug purpose,
-   * you should always use `LazyResult#then`.
+   * PostCSS runners should always use `LazyResult#then`.
    */
   get messages(): Message[]
 
   /**
-   * Processes input CSS through synchronous plugins
-   * and calls `Result#warnings`.
-   *
-   * @return Warnings from plugins.
+   * Options from the `Processor#process` call.
    */
-  warnings(): Warning[]
+  get opts(): ResultOptions
 
   /**
-   * Alias for the `LazyResult#css` property.
-   *
-   * ```js
-   * lazy + '' === lazy.css
-   * ```
-   *
-   * @return Output CSS.
+   * Returns a `Processor` instance, which will be used
+   * for CSS transformations.
    */
-  toString(): string
+  get processor(): Processor
 
   /**
-   * Run plugin in sync way and return `Result`.
+   * Processes input CSS through synchronous plugins
+   * and returns `Result#root`.
    *
-   * @return Result with output content.
+   * This property will only work with synchronous plugins. If the processor
+   * contains any asynchronous plugins it will throw an error.
+   *
+   * PostCSS runners should always use `LazyResult#then`.
    */
-  sync(): Result
+  get root(): RootNode
 
   /**
-   * Run plugin in async way and return `Result`.
-   *
-   * @return Result with output content.
+   * Returns the default string description of an object.
+   * Required to implement the Promise interface.
    */
-  async(): Promise<Result>
+  get [Symbol.toStringTag](): string
 }
+
+declare class LazyResult<
+  RootNode = Document | Root
+> extends LazyResult_<RootNode> {}
+
+export = LazyResult