@sketch-hq/sketch-assistant-types - npm Package Compare versions

Comparing version 5.0.0 to 6.0.0-rc.0

CHANGELOG.md

 # @sketch-hq/sketch-assistant-types
 
+## 6.0.0-rc.0
+
+### Major Changes
+
+- f8a0829: Support for reporting violations that reference multiple Sketch file objects.
+- 81a6e61: Add timeouts to rules.
+- f155f44: Renamed `file` prop in `ProcessedSketchFile` to `original`.
+
 ## 5.0.0
@@ -4,0 +12,0 @@

dist/types.d.ts

@@ -121,5 +121,5 @@ import { FileFormat3 } from '@sketch-hq/sketch-file-format-ts';
     /**
-     * The SketchFile that was processed.
+     * The original SketchFile object that was processed.
      */
-    file: SketchFile;
+    original: SketchFile;
     /**
@@ -178,3 +178,3 @@ * Statistics about the processed file.
  */
-export declare type RunOperation = {
+export declare type CancelToken = {
     cancelled: boolean;
@@ -185,2 +185,8 @@ } | {
 /**
+ * Contains a flag indicating whether a rule has timed out.
+ */
+export declare type TimeoutToken = {
+    timedOut: boolean;
+};
+/**
  * A map of Assistant packages, keyed by Assistant package name. Since the
@@ -217,3 +223,3 @@ * package map is often supplied externally, by an outer layer (e.g. by Sketch
      */
-    operation: RunOperation;
+    cancelToken: CancelToken;
     /**
@@ -223,2 +229,17 @@ * Environment.
     env: AssistantEnv;
+    timeBudgets: {
+        /**
+         * Time budget in milliseconds for the entire run to complete. During the run this budget is
+         * dividedly evenly between each active rule.
+         */
+        totalMs: number;
+        /**
+         * Minimum rule run time in milliseconds, irrespective of its share of the total budget.
+         */
+        minRuleTimeoutMs: number;
+        /**
+         * Maximum rule run time in milliseconds, irrespective of its share of the total budget.
+         */
+        maxRuleTimeoutMs: number;
+    };
 };
@@ -300,3 +321,3 @@ /**
  */
-export declare type PlainRuleError = {
+export declare type RuleError = {
     assistantName: string;
@@ -306,2 +327,3 @@ ruleName: string;
     stack: string;
+    code: 'error' | 'timeout';
 };
@@ -321,5 +343,8 @@ /**
     /**
-     * The Assistant "passed" if there are no ViolationSeverity.error level violations present.
+     * Assistant grades the document as follows:
+     *   "pass"          No violations with severity level "error" present
+     *   "fail"          One or more violations with severitu level "error" present
+     *   "unknown"       Grade could not be determined, for example due to one or more rules timing-out
      */
-    passed: boolean;
+    grade: 'fail' | 'pass' | 'unknown';
     /**
@@ -330,7 +355,7 @@ * One or more `violations` implies the assistant’s rules found issues with the Sketch document.
     /**
-     * One or more `ruleErrors` implies that some rules didn’t run because they encountered errors.
+     * One or more `ruleErrors` implies that some rules encountered errors.
      */
-    ruleErrors: PlainRuleError[];
+    ruleErrors: RuleError[];
     /**
-     * Metadata relating to the Assistant that produced the result, and the rules that were invoked.
+     * Metadata relating to the Assistant that produced the result.
      */
@@ -368,3 +393,2 @@ metadata: {
     assistant: AssistantDefinition;
-    operation: RunOperation;
     getImageMetadata: GetImageMetadata;
@@ -376,3 +400,3 @@ env: AssistantEnv;
  */
-export declare type RuleUtilsCreator = (ruleName: string) => RuleUtils;
+export declare type RuleUtilsCreator = (ruleName: string, timeoutToken: TimeoutToken) => RuleUtils;
 /**
@@ -387,3 +411,3 @@ * Object containing utilities passed into rule functions. Where needed the util functions are
      */
-    report: (report: ReportItem | ReportItem[]) => void;
+    report: (message: string, ...objects: SketchFileObject[]) => void;
     /**
@@ -404,4 +428,13 @@ * Contains an iterator for each type of object in the Sketch file.
      */
-    isObjectIgnoredForRule: (object: SketchFileObject) => boolean;
+    isObjectIgnored: (object: SketchFileObject) => boolean;
     /**
+     * Rules can be a good Assistant citizen by checking the return value of this function during any
+     * long running calculations - if it returns `true` then the rule should bail out of any further
+     * calculations and exit as soon as possible. This function will return `true` for two reasons -
+     * the run has been cancelled entirely, or the current rule has timed-out. Note: If the rule is
+     * mainly driven by the `utils.objects` and `utils.foreignObjects` iterators then there's no need
+     * to call this function, since these loops will be terminated early if required automatically.
+     */
+    shouldExitEarly: () => boolean;
+    /**
      * Get a rule option value by name. Should throw if the rule hasn’t been configured properly in
@@ -461,11 +494,12 @@ * the current assistant context, since it’s essential that every rule activated in an assistant is
 /**
- * Information a rule needs to supply when reporting a violation.
+ * Information about where in a Sketch file a violation relates to.
  */
-export declare type ReportItem = {
-    message: string;
-    object?: SketchFileObject;
+export declare type ViolationLocation = {
+    pointer: string | null;
+    objectId: string | null;
+    objectName: string | null;
 };
 /**
- * A violation collates all the information about a problem, and is the fundamental way an assistant
- * communicates results to the outer environment.
+ * A violation collates all the information about a problem, and is the fundamental way an Assistant
+ * communicates these to the outer environment.
  */
@@ -477,5 +511,6 @@ export declare type Violation = {
     severity: ViolationSeverity;
-    pointer: string | null;
-    objectId: string | null;
-    objectName: string | null;
+    /**
+     * Violations may relate to zero or more locations in a Sketch file.
+     */
+    locations: ViolationLocation[];
 };
@@ -482,0 +517,0 @@ /**

package.json

 {
   "name": "@sketch-hq/sketch-assistant-types",
-  "version": "5.0.0",
+  "version": "6.0.0-rc.0",
   "main": "dist/types",
@@ -5,0 +5,0 @@ "types": "dist/types",

New alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

45284

increased by5.05%

Lines of code

866

increased by4.21%

Worsened metrics

Number of low quality alerts

2

increased by100%

No dependency changes