Programmatic API

/**
 * Lint CSS code or files
 * @param options - Linting configuration and input
 * @returns Promise resolving to linting results
 */
function lint(options: LinterOptions): Promise<LinterResult>;

interface LinterOptions {
  /** File paths or glob patterns to lint */
  files?: string | string[];
  /** Options for globby when resolving file patterns */
  globbyOptions?: GlobbyOptions;
  /** CSS code string to lint directly */
  code?: string;
  /** Optional filename for code-based linting */
  codeFilename?: string;
  /** Stylelint configuration object */
  config?: Config;
  /** Path to configuration file */
  configFile?: string;
  /** Base directory for resolving configuration */
  configBasedir?: string;
  /** Working directory for file operations */
  cwd?: string;
  /** Enable automatic fixing where possible */
  fix?: boolean | FixMode;
  /** Compute edit info for fixes */
  computeEditInfo?: boolean;
  /** Output formatter type or custom formatter */
  formatter?: FormatterType | Formatter;
  /** Cache results for improved performance */
  cache?: boolean;
  /** Cache location path */
  cacheLocation?: string;
  /** Cache strategy */
  cacheStrategy?: string;
  /** Maximum number of warnings before failing */
  maxWarnings?: number;
  /** Ignore disable comments */
  ignoreDisables?: boolean;
  /** Ignore file paths */
  ignorePath?: string | string[];
  /** Ignore patterns for files */
  ignorePattern?: string[];
  /** Custom syntax for non-standard CSS */
  customSyntax?: CustomSyntax;
  /** Disable default ignore patterns */
  disableDefaultIgnores?: boolean;
  /** Enable quiet mode (errors only) */
  quiet?: boolean;
  /** Quiet deprecation warnings */
  quietDeprecationWarnings?: boolean;
  /** Allow empty input without error */
  allowEmptyInput?: boolean;
  /** Report descriptionless disable comments */
  reportDescriptionlessDisables?: boolean;
  /** Report needless disable comments */
  reportNeedlessDisables?: boolean;
  /** Report invalid scope disable comments */
  reportInvalidScopeDisables?: boolean;
  /** Report unscoped disable comments */
  reportUnscopedDisables?: boolean;
  /** Force enable/disable validation of rule options */
  validate?: boolean;
}

import stylelint from "stylelint";
const { lint } = stylelint;

// Lint CSS code string
const result = await lint({
  code: `
    .example {
      color: #ffffff;
      font-weight: bold;
    }
  `,
  config: {
    rules: {
      "color-hex-length": "short",
      "font-weight-notation": "numeric"
    }
  }
});

// Lint files
const fileResult = await lint({
  files: ["src/**/*.css", "!src/vendor/**"],
  configFile: ".stylelintrc.json",
  fix: true
});

// Lint with custom formatter
const jsonResult = await lint({
  files: "styles/*.scss",
  formatter: "json",
  customSyntax: "postcss-scss"
});

interface LinterResult {
  /** Working directory from which linter was run */
  cwd: string;
  /** Array of individual file results */
  results: LintResult[];
  /** Whether any errors were found */
  errored: boolean;
  /** Formatted report string */
  report: string;
  /** Autofixed code (when fix option is enabled) */
  code?: string;
  /** @deprecated Use report instead */
  output: string;
  /** Information about max warnings exceeded */
  maxWarningsExceeded?: {
    maxWarnings: number;
    foundWarnings: number;
  };
  /** Reports on disable comment usage */
  reportedDisables: DisableReportEntry[];
  needlessDisables?: DisableReportEntry[];
  invalidScopeDisables?: DisableReportEntry[];
  descriptionlessDisables?: DisableReportEntry[];
  /** Rule metadata information */
  ruleMetadata: { [ruleName: string]: Partial<RuleMeta> };
}

interface LintResult {
  /** File path or undefined for code-based linting */
  source?: string;
  /** Array of linting warnings and errors */
  warnings: Warning[];
  /** Whether this file had any errors */
  errored?: boolean;
  /** Whether this file was ignored */
  ignored?: boolean;
  /** Deprecation warnings */
  deprecations: {
    text: string;
    reference?: string;
  }[];
  /** Invalid option warnings */
  invalidOptionWarnings: {
    text: string;
  }[];
  /** CSS parse errors */
  parseErrors: (PostCSS.Warning & {
    stylelintType: 'parseError';
  })[];
}

interface Warning {
  /** Line number of the issue */
  line: number;
  /** Column number of the issue */
  column: number;
  /** End line number (for ranges) */
  endLine?: number;
  /** End column number (for ranges) */
  endColumn?: number;
  /** Rule name that generated this warning */
  rule: string;
  /** Severity level */
  severity: 'warning' | 'error';
  /** Human-readable message text */
  text: string;
  /** URL to rule documentation */
  url?: string;
  /** Auto-fix information if available */
  fix?: EditInfo;
}

type FixMode = 'lax' | 'strict';

interface EditInfo {
  /** Start and end positions for the fix */
  range: [number, number];
  /** Replacement text */
  text: string;
}

type CustomSyntax = string | PostCSS.Syntax;

// Examples of custom syntax usage
const scssResult = await lint({
  files: "src/**/*.scss",
  customSyntax: "postcss-scss"
});

const lessResult = await lint({
  files: "src/**/*.less", 
  customSyntax: "postcss-less"
});

try {
  const result = await lint({
    code: invalidCSS,
    config: { rules: { "color-no-invalid-hex": true } }
  });
  
  if (result.errored) {
    console.error("Linting failed:");
    result.results.forEach(fileResult => {
      fileResult.warnings.forEach(warning => {
        if (warning.severity === 'error') {
          console.error(`${warning.rule}: ${warning.text}`);
        }
      });
    });
  }
} catch (error) {
  console.error("Linting error:", error.message);
}