@kb-labs/qa-contracts 2.88.0 → 2.93.0

package/dist/index.d.ts

@@ -53,10 +53,24 @@ interface QACheckConfig {
      * - "perPackage" (default): run in each discovered package directory
      * - "scopePath": run once in the sub-repo root (e.g. platform/kb-labs-cli/)
      * - "repoRoot": run once in the workspace root
+     * - "diffOnly": run per-package, but only for packages containing files changed in the current branch (git diff base..HEAD)
+     * - "newFiles": run per-package, but only for packages containing files added in the current branch (git diff --diff-filter=A)
      */
-    runIn?: 'perPackage' | 'scopePath' | 'repoRoot';
+    runIn?: 'perPackage' | 'scopePath' | 'repoRoot' | 'diffOnly' | 'newFiles';
     /** Display icon (emoji, e.g. "🔒"). Used in CLI output and REST API. */
     icon?: string;
+    /**
+     * How a failure affects the overall QA run.
+     * - "blocker" (default): failure sets status to "failed" and appears in blockers[]
+     * - "warning": failure does not change status, appears in warnings[]
+     * - "info": recorded but does not appear in blockers[] or warnings[]
+     */
+    severity?: 'blocker' | 'warning' | 'info';
+    /**
+     * If true, write per-check trend history to .kb/qa/trends/<id>.json in addition to the global history.
+     * Useful for tracking long-term quality trends for specific checks without polluting global history.
+     */
+    trending?: boolean;
 }
 /**
  * Filter which packages are discovered and checked.
@@ -103,6 +117,38 @@ interface CategoryConfig {
     packages: string[];
 }
 
+/**
+ * Structured output types for QA checks.
+ * Checks with parser:"json" should return TypedCheckOutput on stdout.
+ */
+/**
+ * A single actionable finding from a check.
+ */
+interface CheckItem {
+    /** File path, package name, or other target identifier */
+    target: string;
+    /** Human-readable description of the issue */
+    message: string;
+    /** Concrete action for the agent to take (optional) */
+    fix?: string;
+}
+/**
+ * Structured JSON output expected from checks with parser:"json".
+ * The check script should write this to stdout.
+ *
+ * @example
+ * process.stdout.write(JSON.stringify({
+ *   ok: false,
+ *   items: [
+ *     { target: 'src/foo.ts', message: 'no test file found', fix: 'create src/foo.test.ts' }
+ *   ]
+ * }));
+ */
+interface TypedCheckOutput {
+    ok: boolean;
+    items?: CheckItem[];
+}
+
 /**
  * Types of checks the QA plugin can run.
  */
@@ -119,6 +165,8 @@ interface CheckResult {
     skipped: string[];
     /** Error messages keyed by package name */
     errors: Record<string, string>;
+    /** Structured findings keyed by target (file/package). Populated when check uses parser:"json" and returns CheckItem[]. */
+    details?: Record<string, CheckItem[]>;
 }
 /**
  * Combined results of all QA check types.
@@ -240,6 +288,17 @@ interface HistoryEntry {
         skipped: number;
     }>;
     failedPackages: Record<string, string[]>;
+    /**
+     * Arbitrary context from the caller (e.g. workflow step, agent, task).
+     * Passed via --context flag as JSON. QA stores it as-is without interpretation.
+     */
+    runContext?: {
+        taskId?: string;
+        sessionId?: string;
+        agentId?: string;
+        workflowRunId?: string;
+        [key: string]: unknown;
+    };
 }
 /**
  * Trend analysis result for a single check type.
@@ -326,6 +385,13 @@ interface ReportSummary {
     failed: number;
     skipped: number;
 }
+/**
+ * A grouped set of findings for one check in the agent-facing report.
+ */
+interface ReportCheckFindings {
+    check: string;
+    items: CheckItem[];
+}
 /**
  * Full QA report — returned by json reporter.
  */
@@ -336,6 +402,16 @@ interface QAReport {
     failures: Record<string, string[]>;
     errors: Record<string, Record<string, string>>;
     baseline: BaselineDiff | null;
+    /**
+     * Blocker findings — checks with severity:"blocker" (default) that failed.
+     * Each entry has structured CheckItem[] for the agent to act on.
+     */
+    blockers: ReportCheckFindings[];
+    /**
+     * Warning findings — checks with severity:"warning" that failed.
+     * Does not affect overall status, but agent should review.
+     */
+    warnings: ReportCheckFindings[];
 }
 
 /**
@@ -2188,4 +2264,4 @@ declare const QA_FULL_ROUTES: {
 };
 type QARoute = typeof QA_ROUTES[keyof typeof QA_ROUTES];
 
-export { type BaselineCheckSnapshot, type BaselineDiff, type BaselineSnapshot, type CategoryConfig, type CategoryGroup, type CheckDiff, type CheckResult, type CheckType, type EnrichedTrendResult, type ErrorGroup, type GitInfo, type GroupSummary, type GroupedResults, HISTORY_MAX_ENTRIES, type HistoryEntry, PATHS, type PackageCheckDetail, type PackageFilter, type PackageStatus, type PackageTimelineEntry, type PackageTimelineResponse, type PackagesConfig, type QABaselineDiffRequest, QABaselineDiffRequestSchema, type QABaselineDiffResponse, QABaselineDiffResponseSchema, type QABaselineRequest, QABaselineRequestSchema, type QABaselineResponse, QABaselineResponseSchema, type QABaselineUpdateRequest, QABaselineUpdateRequestSchema, type QABaselineUpdateResponse, QABaselineUpdateResponseSchema, type QACheckConfig, type QADetailsRequest, QADetailsRequestSchema, type QADetailsResponse, QADetailsResponseSchema, type QAEnrichedTrendsResponse, QAEnrichedTrendsResponseSchema, type QAErrorGroupsRequest, QAErrorGroupsRequestSchema, type QAErrorGroupsResponse, QAErrorGroupsResponseSchema, type QAHistoryRequest, QAHistoryRequestSchema, type QAHistoryResponse, QAHistoryResponseSchema, type QALatestRequest, QALatestRequestSchema, type QALatestResponse, QALatestResponseSchema, type QAPackageTimelineRequest, QAPackageTimelineRequestSchema, type QAPackageTimelineResponse, QAPackageTimelineResponseSchema, type QAPluginConfig, type QARegressionsRequest, QARegressionsRequestSchema, type QARegressionsResponse, QARegressionsResponseSchema, type QAReport, type QAResults, type QARoute, type QARunCheckRequest, QARunCheckRequestSchema, type QARunCheckResponse, QARunCheckResponseSchema, type QARunOptions, type QARunRequest, QARunRequestSchema, type QARunResponse, QARunResponseSchema, type QARunResult, QASummaryCheckSchema, type QASummaryRequest, QASummaryRequestSchema, type QASummaryResponse, QASummaryResponseSchema, type QATrendsRequest, QATrendsRequestSchema, type QATrendsResponse, QATrendsResponseSchema, QA_BASE_PATH, QA_DATA_DIR, QA_FULL_ROUTES, QA_ROUTES, type RegressionEntry, type RegressionResult, type RepoGroup, type ReportSummary, type SubmoduleInfo, TRENDS_WINDOW, type TrendChangelogEntry, type TrendResult, type TrendTimeSeriesPoint, type WorkspacePackage, getCheckIcon, getCheckLabel };
+export { type BaselineCheckSnapshot, type BaselineDiff, type BaselineSnapshot, type CategoryConfig, type CategoryGroup, type CheckDiff, type CheckItem, type CheckResult, type CheckType, type EnrichedTrendResult, type ErrorGroup, type GitInfo, type GroupSummary, type GroupedResults, HISTORY_MAX_ENTRIES, type HistoryEntry, PATHS, type PackageCheckDetail, type PackageFilter, type PackageStatus, type PackageTimelineEntry, type PackageTimelineResponse, type PackagesConfig, type QABaselineDiffRequest, QABaselineDiffRequestSchema, type QABaselineDiffResponse, QABaselineDiffResponseSchema, type QABaselineRequest, QABaselineRequestSchema, type QABaselineResponse, QABaselineResponseSchema, type QABaselineUpdateRequest, QABaselineUpdateRequestSchema, type QABaselineUpdateResponse, QABaselineUpdateResponseSchema, type QACheckConfig, type QADetailsRequest, QADetailsRequestSchema, type QADetailsResponse, QADetailsResponseSchema, type QAEnrichedTrendsResponse, QAEnrichedTrendsResponseSchema, type QAErrorGroupsRequest, QAErrorGroupsRequestSchema, type QAErrorGroupsResponse, QAErrorGroupsResponseSchema, type QAHistoryRequest, QAHistoryRequestSchema, type QAHistoryResponse, QAHistoryResponseSchema, type QALatestRequest, QALatestRequestSchema, type QALatestResponse, QALatestResponseSchema, type QAPackageTimelineRequest, QAPackageTimelineRequestSchema, type QAPackageTimelineResponse, QAPackageTimelineResponseSchema, type QAPluginConfig, type QARegressionsRequest, QARegressionsRequestSchema, type QARegressionsResponse, QARegressionsResponseSchema, type QAReport, type QAResults, type QARoute, type QARunCheckRequest, QARunCheckRequestSchema, type QARunCheckResponse, QARunCheckResponseSchema, type QARunOptions, type QARunRequest, QARunRequestSchema, type QARunResponse, QARunResponseSchema, type QARunResult, QASummaryCheckSchema, type QASummaryRequest, QASummaryRequestSchema, type QASummaryResponse, QASummaryResponseSchema, type QATrendsRequest, QATrendsRequestSchema, type QATrendsResponse, QATrendsResponseSchema, QA_BASE_PATH, QA_DATA_DIR, QA_FULL_ROUTES, QA_ROUTES, type RegressionEntry, type RegressionResult, type RepoGroup, type ReportCheckFindings, type ReportSummary, type SubmoduleInfo, TRENDS_WINDOW, type TrendChangelogEntry, type TrendResult, type TrendTimeSeriesPoint, type TypedCheckOutput, type WorkspacePackage, getCheckIcon, getCheckLabel };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kb-labs/qa-contracts",
   "description": "Contracts for KB Labs QA Plugin — types, interfaces, and constants for QA checks, baselines, and history tracking.",
-  "version": "2.88.0",
+  "version": "2.93.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -26,7 +26,7 @@
     "tsup": "^8.5.0",
     "typescript": "^5.6.3",
     "vitest": "^3.2.4",
-    "@kb-labs/devkit": "2.88.0"
+    "@kb-labs/devkit": "2.93.0"
   },
   "engines": {
     "node": ">=20.0.0",