postcss 8.5.26: Result#warnings

# PostCSS Result#warnings Diagnostic and Linting Behavior

## Known Solution Search
A query for known solutions regarding `verify Result#warnings in pkg:npm/postcss@8.5.26` returned `NO_SAFE_MATCH` across cached shards.

## Pinned Release
- Package: `postcss`
- Exact version: `8.5.26`
- Ecosystem: `npm`
- Target symbol: `Result#warnings`

## Observed Behaviour

### 1. Warning Filtering from Result Messages
PostCSS stores all processing messages in `result.messages`. While plugins can attach arbitrary message objects (e.g. `type: 'dependency'`), `result.warnings()` filters the messages list and returns only items with `type: 'warning'`.

### 2. Node and Result Warning Registration
Warnings can be emitted via `result.warn(message, opts)` or `node.warn(result, message, opts)`. When attached to AST nodes, the `Warning` object captures the node reference, calculated line and column positions, and plugin name.

### 3. Clean CSS Handling
When no plugins or nodes emit warnings during transformation, `result.warnings()` returns an empty array `[]`.

### 4. Span and Range Resolution
Passing `index`, `endIndex`, or `word` to `result.warn()` calculates precise `line`, `column`, `endLine`, and `endColumn` coordinates relative to the input CSS source.

### 5. Warning String Formatting
Calling `.toString()` on a `Warning` instance renders formatted diagnostic text including the plugin name, source file or `<css input>`, line/column positions, and warning message.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify Result#warnings in pkg:npm/postcss@8.5.26
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/postcss@8.5.26
Demonstrate these symbols/APIs:
  - Result#warnings

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:039d1ebba129247decb2920680614a37816a6a0f089ec5c4a8f51d6e6aac190b","contract":["assert result.warnings() filters messages array to return only warning objects while ignoring non-warning message types like dependency or custom data","assert result.warn() and node.warn() populate warning properties including text, type, plugin, line, and column from AST node positions","assert result.warnings() returns an empty array when no warnings are registered during CSS processing","assert warning options index, endIndex, and word resolve precise line and column span coordinates on target AST declaration nodes","assert warning.toString() formats diagnostic messages with originating plugin name, input source name, and line/column coordinates"],"goal":"verify Result#warnings in pkg:npm/postcss@8.5.26","kind":"HOW","packages":["pkg:npm/postcss@8.5.26"],"schemaVersion":1,"symbols":["Result#warnings"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/postcss@8.5.26"],"schemaVersion":1,"subject":"pkg:npm/postcss@8.5.26","symbols":["Result#warnings"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-postcss-result-warnings",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-postcss-result-warnings",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "postcss": "8.5.26"
      }
    },
    "node_modules/nanoid": {
      "version": "3.3.18",
      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
      "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/ai"
        }
      ],
      "license": "MIT",
      "bin": {
        "nanoid": "bin/nanoid.cjs"
      },
      "engines": {
        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
      }
    },
    "node_modules/picocolors": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
      "license": "ISC"
    },
    "node_modules/postcss": {
      "version": "8.5.26",
      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",
      "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==",
      "funding": [
        {
          "type": "opencollective",
          "url": "https://opencollective.com/postcss/"
        },
        {
          "type": "tidelift",
          "url": "https://tidelift.com/funding/github/npm/postcss"
        },
        {
          "type": "github",
          "url": "https://github.com/sponsors/ai"
        }
      ],
      "license": "MIT",
      "dependencies": {
        "nanoid": "^3.3.17",
        "picocolors": "^1.1.1",
        "source-map-js": "^1.2.1"
      },
      "engines": {
        "node": "^10 || ^12 || >=14"
      }
    },
    "node_modules/source-map-js": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
      "license": "BSD-3-Clause",
      "engines": {
        "node": ">=0.10.0"
      }
    }
  }
}

{
  "name": "sample-postcss-result-warnings",
  "version": "1.0.0",
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "postcss": "8.5.26"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify Result#warnings in pkg:npm/postcss@8.5.26",
  "kind": "HOW",
  "packages": [
    "pkg:npm/postcss@8.5.26"
  ],
  "symbols": [
    "Result#warnings"
  ]
}

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const postcss = require('postcss');

// 1. assert result.warnings() filters messages array to return only warning objects while ignoring non-warning message types like dependency or custom data
{
  const filterPlugin = () => ({
    postcssPlugin: 'filter-plugin',
    Declaration(decl, { result }) {
      if (decl.prop === '-webkit-transform') {
        result.warn('Deprecated vendor prefix', { node: decl });
      }
    },
    Once(root, { result }) {
      result.messages.push({
        type: 'dependency',
        plugin: 'filter-plugin',
        file: 'theme.css'
      });
      result.messages.push({
        type: 'custom-metric',
        plugin: 'filter-plugin',
        durationMs: 12
      });
    }
  });
  filterPlugin.postcss = true;

  const css = 'div { -webkit-transform: scale(2); color: #333; }';
  const result = postcss([filterPlugin()]).process(css, { from: 'style.css' });

  assert.equal(result.messages.length, 3);
  const warnings = result.warnings();
  assert.equal(Array.isArray(warnings), true);
  assert.equal(warnings.length, 1);
  assert.equal(warnings[0].type, 'warning');
  assert.equal(warnings[0].text, 'Deprecated vendor prefix');
  assert.equal(warnings[0].plugin, 'filter-plugin');
}

// 2. assert result.warn() and node.warn() populate warning properties including text, type, plugin, line, and column from AST node positions
{
  const linterPlugin = () => ({
    postcssPlugin: 'linter-plugin',
    Rule(rule, { result }) {
      if (rule.selector.includes('blink')) {
        rule.warn(result, 'Disallowed blink selector', { word: 'blink' });
      }
    },
    Declaration: {
      color(decl, { result }) {
        if (decl.value === 'red') {
          result.warn('Color red is forbidden', { node: decl, word: 'red' });
        }
      }
    }
  });
  linterPlugin.postcss = true;

  const css = 'blink {\n  color: red;\n}';
  const result = postcss([linterPlugin()]).process(css);
  const warnings = result.warnings();

  assert.equal(warnings.length, 2);

  // Rule warning via rule.warn
  assert.equal(warnings[0].type, 'warning');
  assert.equal(warnings[0].plugin, 'linter-plugin');
  assert.equal(warnings[0].text, 'Disallowed blink selector');
  assert.equal(warnings[0].line, 1);
  assert.equal(warnings[0].column, 1);
  assert.equal(warnings[0].word, 'blink');
  assert.equal(warnings[0].node.type, 'rule');

  // Declaration warning via result.warn
  assert.equal(warnings[1].type, 'warning');
  assert.equal(warnings[1].plugin, 'linter-plugin');
  assert.equal(warnings[1].text, 'Color red is forbidden');
  assert.equal(warnings[1].line, 2);
  assert.equal(warnings[1].column, 10);
  assert.equal(warnings[1].word, 'red');
  assert.equal(warnings[1].node.type, 'decl');
}

// 3. assert result.warnings() returns an empty array when no warnings are registered during CSS processing
{
  const cleanCss = 'header { margin: 0 auto; display: flex; }';
  const result = postcss([]).process(cleanCss, { from: undefined });
  const warnings = result.warnings();

  assert.equal(Array.isArray(warnings), true);
  assert.equal(warnings.length, 0);
  assert.deepEqual(warnings, []);
}

// 4. assert warning options index, endIndex, and word resolve precise line and column span coordinates on target AST declaration nodes
{
  const spanPlugin = () => ({
    postcssPlugin: 'span-plugin',
    Declaration(decl, { result }) {
      if (decl.prop === 'padding') {
        result.warn('Padding sub-value flagged', {
          node: decl,
          index: 2,
          endIndex: 6
        });
      }
    }
  });
  spanPlugin.postcss = true;

  const css = 'section {\n  padding: 10px 20px;\n}';
  const result = postcss([spanPlugin()]).process(css);
  const warnings = result.warnings();

  assert.equal(warnings.length, 1);
  const w = warnings[0];
  assert.equal(w.line, 2);
  assert.equal(w.column, 5);
  assert.equal(w.endLine, 2);
  assert.equal(w.endColumn, 9);
  assert.equal(w.index, 2);
  assert.equal(w.endIndex, 6);
}

// 5. assert warning.toString() formats diagnostic messages with originating plugin name, input source name, and line/column coordinates
{
  const namedPlugin = () => ({
    postcssPlugin: 'diagnostic-plugin',
    Declaration: {
      opacity(decl, { result }) {
        result.warn('Opacity deprecated in favor of rgba', { node: decl });
      }
    }
  });
  namedPlugin.postcss = true;

  const css = 'nav {\n  opacity: 0.8;\n}';
  const resultWithFrom = postcss([namedPlugin()]).process(css, { from: 'nav.css' });
  assert.match(
    resultWithFrom.warnings()[0].toString(),
    /diagnostic-plugin: .*nav\.css:2:3: Opacity deprecated in favor of rgba/
  );

  const resultWithoutFrom = postcss([namedPlugin()]).process(css);
  assert.equal(
    resultWithoutFrom.warnings()[0].toString(),
    'diagnostic-plugin: <css input>:2:3: Opacity deprecated in favor of rgba'
  );
}