@zealakit/css-doctor-binding 1.0.0 → 1.1.0

package/index.d.ts

@@ -296,3 +296,238 @@ export interface JsPipelineOutput {
  * stylesheet/AST cannot be processed.
  */
 export declare function optimizeCss(input: JsPipelineInput): JsPipelineOutput
+/** Combined pipeline output + optimization report from a single native run. */
+export interface JsOptimizeExplained {
+  pipeline: JsPipelineOutput
+  reportJson: string
+}
+/**
+ * Runs the optimization pipeline once and returns both chunks and a report.
+ *
+ * Prefer this over calling [`optimize_css`] and [`optimize_css_report`]
+ * separately to avoid double parsing/splitting.
+ *
+ * # Errors
+ *
+ * Rejects when the pipeline or report builder fails.
+ */
+export declare function optimizeCssExplained(input: JsPipelineInput, maxSelectorDecisions?: number | undefined | null): JsOptimizeExplained
+/**
+ * Runs the optimization pipeline and returns a versioned report JSON document
+ * that includes decisions, metrics, and chunk inventory.
+ *
+ * # Errors
+ *
+ * Rejects when the pipeline or report builder fails.
+ */
+export declare function optimizeCssReport(input: JsPipelineInput, maxSelectorDecisions?: number | undefined | null): string
+/** Lists built-in autofix rules as JSON. */
+export declare function listCssFixes(): string
+/** Autofix input. */
+export interface JsFixInput {
+  cssContent: string
+  filePath?: string
+  dryRun?: boolean
+  rules?: Array<string>
+  includeReview?: boolean
+}
+/**
+ * Plans or applies safe CSS autofixes. Returns a JSON `FixApplicationResult`.
+ *
+ * # Errors
+ *
+ * Rejects for parse/serialize failures or unsafe rule selection.
+ */
+export declare function applyCssFixes(input: JsFixInput): string
+/** Optional weights for CSS Health Score dimensions (must be >= 0). */
+export interface JsHealthWeights {
+  selectorComplexity?: number
+  duplicateRules?: number
+  cssSizeEfficiency?: number
+  deadCss?: number
+  variableConsistency?: number
+}
+/** Optional thresholds for CSS Health Score analyzers. */
+export interface JsHealthThresholds {
+  highSpecificityClasses?: number
+  highSpecificityIds?: number
+  deepCombinatorCount?: number
+  deepNestingDepth?: number
+  longSelectorTokenCount?: number
+  largeStylesheetBytes?: number
+  criticalStylesheetBytes?: number
+  heavyRuleDeclarations?: number
+  manySelectors?: number
+}
+/** Input for [`evaluate_css_health`]. */
+export interface JsHealthInput {
+  cssContent: string
+  filePath?: string
+  sizeBytes?: number
+  weights?: JsHealthWeights
+  thresholds?: JsHealthThresholds
+}
+/** One health diagnostic finding. */
+export interface JsHealthDiagnostic {
+  code: string
+  severity: string
+  category: string
+  message: string
+  filePath?: string
+  location?: JsSourceLocation
+  selector?: string
+  remediation: string
+  certainty: string
+}
+/** Score metadata for one health dimension. */
+export interface JsDimensionScore {
+  id: string
+  score?: number
+  weight: number
+  effectiveWeight: number
+  evaluated: boolean
+  issueCount: number
+  errorCount: number
+  warningCount: number
+  infoCount: number
+  diagnosticCodes: Array<string>
+  recommendations: Array<string>
+  note?: string
+}
+/** Aggregate counters for a health report. */
+export interface JsHealthScoreSummary {
+  files: number
+  rules: number
+  selectors: number
+  declarations: number
+  sizeBytes: number
+  errors: number
+  warnings: number
+  suggestions: number
+  analysisMs: number
+}
+/** Complete CSS Health Score report. */
+export interface JsHealthReport {
+  schemaVersion: number
+  overall: number
+  grade: string
+  status: string
+  dimensions: Array<JsDimensionScore>
+  summary: JsHealthScoreSummary
+  diagnostics: Array<JsHealthDiagnostic>
+  recommendations: Array<string>
+}
+/**
+ * Evaluates CSS Health Score for a single stylesheet.
+ *
+ * # Errors
+ *
+ * Rejects when configuration is invalid or CSS cannot be parsed.
+ */
+export declare function evaluateCssHealth(input: JsHealthInput): JsHealthReport
+/** One stylesheet entry for multi-file health evaluation. */
+export interface JsHealthFileInput {
+  cssContent: string
+  filePath?: string
+  sizeBytes?: number
+}
+/** Multi-file health evaluation input. */
+export interface JsHealthBatchInput {
+  files: Array<JsHealthFileInput>
+  weights?: JsHealthWeights
+  thresholds?: JsHealthThresholds
+}
+/**
+ * Evaluates and merges CSS Health Score across multiple stylesheets.
+ *
+ * # Errors
+ *
+ * Rejects when configuration is invalid or any stylesheet cannot be parsed.
+ */
+export declare function evaluateCssHealthBatch(input: JsHealthBatchInput): JsHealthReport
+/** File entry used when creating a baseline document. */
+export interface JsBaselineFileInput {
+  path: string
+  cssContent: string
+  sizeBytes?: number
+}
+/** Optional Git metadata for a baseline. */
+export interface JsBaselineGitMetadata {
+  commit?: string
+  branch?: string
+  dirty?: boolean
+}
+/** Optional project metadata for a baseline. */
+export interface JsBaselineProjectMetadata {
+  name?: string
+  root?: string
+}
+/** Input for [`create_baseline`]. */
+export interface JsBaselineCreateInput {
+  files: Array<JsBaselineFileInput>
+  toolVersion: string
+  createdAt?: string
+  patterns?: Array<string>
+  threshold?: number
+  project?: JsBaselineProjectMetadata
+  git?: JsBaselineGitMetadata
+  weights?: JsHealthWeights
+  thresholds?: JsHealthThresholds
+}
+/** Validation outcome for a baseline document. */
+export interface JsBaselineValidationResult {
+  status: string
+  message?: string
+}
+/** Comparison tolerances for regression detection. */
+export interface JsCompareOptions {
+  scoreTolerance?: number
+  sizeAbsoluteToleranceBytes?: number
+  sizeIncreasePercent?: number
+  countAbsoluteTolerance?: number
+  countIncreasePercent?: number
+}
+/** Minimum dimension score gate. */
+export interface JsMinDimensionScore {
+  id: string
+  minScore: number
+}
+/** Quality-gate configuration for regression comparison. */
+export interface JsQualityGateConfig {
+  minScore?: number
+  minDimensionScores?: Array<JsMinDimensionScore>
+  maxCssSize?: number
+  maxSizeIncreasePercent?: number
+  maxNewErrors?: number
+  maxNewWarnings?: number
+  failOnRegression?: boolean
+  failOnNewErrors?: boolean
+  failOnNewDiagnostics?: boolean
+}
+/**
+ * Creates a versioned baseline JSON document from CSS files.
+ *
+ * # Errors
+ *
+ * Rejects when configuration is invalid, CSS cannot be parsed, or
+ * serialization fails.
+ */
+export declare function createBaseline(input: JsBaselineCreateInput): string
+/**
+ * Validates a baseline JSON document.
+ *
+ * # Errors
+ *
+ * Rejects when the JSON cannot be parsed.
+ */
+export declare function validateBaseline(baselineJson: string, toolVersion: string): JsBaselineValidationResult
+/**
+ * Compares a stored baseline against a current baseline snapshot.
+ *
+ * Returns a versioned regression report as pretty JSON.
+ *
+ * # Errors
+ *
+ * Rejects when either document is invalid JSON or options are invalid.
+ */
+export declare function compareBaselines(baselineJson: string, currentJson: string, options?: JsCompareOptions | undefined | null, gates?: JsQualityGateConfig | undefined | null): string

package/index.js

@@ -310,7 +310,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { JsSelectorKind, analyzeCss, analyzeCssAsync, analyzeCssJson, splitCssByPages, JsPipelineChunkKind, optimizeCss } = nativeBinding
+const { JsSelectorKind, analyzeCss, analyzeCssAsync, analyzeCssJson, splitCssByPages, JsPipelineChunkKind, optimizeCss, optimizeCssExplained, optimizeCssReport, listCssFixes, applyCssFixes, evaluateCssHealth, evaluateCssHealthBatch, createBaseline, validateBaseline, compareBaselines } = nativeBinding
 
 module.exports.JsSelectorKind = JsSelectorKind
 module.exports.analyzeCss = analyzeCss
@@ -319,3 +319,12 @@ module.exports.analyzeCssJson = analyzeCssJson
 module.exports.splitCssByPages = splitCssByPages
 module.exports.JsPipelineChunkKind = JsPipelineChunkKind
 module.exports.optimizeCss = optimizeCss
+module.exports.optimizeCssExplained = optimizeCssExplained
+module.exports.optimizeCssReport = optimizeCssReport
+module.exports.listCssFixes = listCssFixes
+module.exports.applyCssFixes = applyCssFixes
+module.exports.evaluateCssHealth = evaluateCssHealth
+module.exports.evaluateCssHealthBatch = evaluateCssHealthBatch
+module.exports.createBaseline = createBaseline
+module.exports.validateBaseline = validateBaseline
+module.exports.compareBaselines = compareBaselines

package/package.json

@@ -1,7 +1,29 @@
 {
   "name": "@zealakit/css-doctor-binding",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Native Node.js bindings for the css-doctor CSS analysis engine",
+  "keywords": [
+    "css",
+    "css-doctor",
+    "css-analysis",
+    "css-optimizer",
+    "dead-code-elimination",
+    "unused-css",
+    "purgecss",
+    "critical-css",
+    "css-splitting",
+    "page-coverage",
+    "lightningcss",
+    "native-addon",
+    "napi",
+    "napi-rs",
+    "rust",
+    "nodejs",
+    "performance",
+    "web-performance",
+    "stylesheet",
+    "frontend"
+  ],
   "author": "nqhed - Huy Edward Nguyen",
   "license": "MIT",
   "main": "index.js",
@@ -14,6 +36,7 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "index.d.cts",
     "*.node",
     "README.md",
     "README_VI.md",
@@ -38,11 +61,11 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@zealakit/css-doctor-binding-darwin-arm64": "1.0.0",
-    "@zealakit/css-doctor-binding-darwin-x64": "1.0.0",
-    "@zealakit/css-doctor-binding-linux-x64-gnu": "1.0.0",
-    "@zealakit/css-doctor-binding-linux-x64-musl": "1.0.0",
-    "@zealakit/css-doctor-binding-win32-x64-msvc": "1.0.0"
+    "@zealakit/css-doctor-binding-darwin-arm64": "1.1.0",
+    "@zealakit/css-doctor-binding-darwin-x64": "1.1.0",
+    "@zealakit/css-doctor-binding-linux-x64-gnu": "1.1.0",
+    "@zealakit/css-doctor-binding-linux-x64-musl": "1.1.0",
+    "@zealakit/css-doctor-binding-win32-x64-msvc": "1.1.0"
   },
   "bugs": {
     "url": "https://github.com/zealakit/css-doctor/issues"