@kb-labs/policy-contracts 0.5.0

package/LICENSE

@@ -0,0 +1,4 @@
+This project is licensed under the same terms as the KB Labs Plugin Template root project.
+
+See the root LICENSE file at the repository root for full details.
+

package/README.md

@@ -0,0 +1,90 @@
+# @kb-labs/plugin-template-contracts
+
+Lightweight public contracts package for the plugin: it describes guaranteed artifacts, commands, workflows, API payloads, and the version of these promises.
+
+## Why this package exists
+
+Every KB Labs plugin is expected to publish a clear, lightweight “promise” to the rest of the ecosystem. This package is that promise: it contains only types, manifests, and validation helpers, so other teams (CLI, Workflow Engine, Studio, REST, marketplace tooling) can rely on a single source of truth without dragging in plugin runtime code.
+
+## Quick start checklist
+
+1. Clone this package as part of your plugin workspace (`packages/contracts`).
+2. Update `pluginContractsManifest` with your plugin ID and initial artifacts/commands.
+3. Adjust Zod schemas in `src/schema.ts` (or add new ones) to match your payloads.
+4. Bump `contractsVersion` whenever the public promise changes (SemVer rules below).
+5. Run `pnpm test` and `pnpm type-check` to ensure the manifest validates.
+6. Import the manifest in your CLI/REST/workflow code to avoid hard-coded IDs.
+
+### Renaming this package
+
+When you turn the template into your own plugin:
+- Change the npm name in `package.json` (e.g. `@kb-labs/my-plugin-contracts`).
+- Update `pluginContractsManifest.pluginId` in `src/contract.ts`.
+- Adjust aliases in `tsconfig.paths.json` and imports across the workspace (`@kb-labs/plugin-template-contracts` → your new name).
+- Replace sample artifact IDs (`template.hello.*`) with your own naming scheme.
+
+## What's inside
+
+- `pluginContractsManifest` — the single source of truth for the plugin's public capabilities
+- TypeScript types (`src/types`) and Zod schemas (`src/schema`) for artifacts, commands, workflows, and API payloads
+- `parsePluginContracts` utility for runtime validation of the manifest and third-party contracts
+
+## Versioning rules
+
+- `contractsVersion` follows SemVer and is **independent** from the plugin's npm version.
+- **MAJOR** — breaking changes (removing/renaming artifacts, changing payload formats).
+- **MINOR** — backwards-compatible extensions (new artifacts, commands, fields).
+- **PATCH** — documentation/metadata updates without altering payload formats.
+
+## Minimal manifest example
+
+```ts
+import type { PluginContracts } from '@kb-labs/plugin-template-contracts';
+
+export const pluginContractsManifest: PluginContracts = {
+  schema: 'kb.plugin.contracts/1',
+  pluginId: '@kb-labs/my-plugin',
+  contractsVersion: '1.0.0',
+  artifacts: {
+    'my-plugin.result': {
+      id: 'my-plugin.result',
+      kind: 'json',
+      description: 'Primary output of the CLI command.'
+    }
+  }
+  // commands/workflows/api can be added later when needed
+};
+```
+
+## Optional sections
+
+All additional sections are **optional** — include only what your plugin actually supports:
+
+- `commands` — define CLI or workflow commands that produce/consume artifacts.
+- `workflows` — describe composed workflows and their steps.
+- `api` — document REST (or future surfaces) when the plugin exposes them.
+
+If your plugin only ships a CLI command, keep `commands` + `artifacts` and omit `workflows`/`api`. The Zod schema accepts missing sections.
+
+## Usage in plugin code
+
+```ts
+import { pluginContractsManifest } from '@kb-labs/plugin-template-contracts';
+
+const helloArtifactId = pluginContractsManifest.artifacts['template.hello.greeting'].id;
+```
+
+Use the manifest to avoid magic strings, assert that required artifacts exist, or log which promises were fulfilled.
+
+## Who relies on the contract
+
+- **Workflow Engine** — verifies allowed steps, required artifacts, and matches produced results with the contract.
+- **Studio** — builds UI and hints based on declared artifacts and commands.
+- **CLI / REST / other plugins** — reuse types and schemas as the source of truth, validate inputs/outputs.
+- **Marketplace & QA tooling** — checks plugin compatibility and correctness before publishing.
+
+## Looking ahead
+
+- Generate JSON Schema / OpenAPI from the `api` contract surface.
+- Add automatic inspectors in Studio and validators for the marketplace.
+

package/dist/index.d.ts

@@ -0,0 +1,339 @@
+import { z } from 'zod';
+
+type PolicySeverity = 'error' | 'warning';
+interface PolicyViolation {
+    rule: string;
+    severity: PolicySeverity;
+    message: string;
+    package?: string;
+    detail?: string;
+    file?: string;
+}
+interface RepoCheckResult {
+    path: string;
+    category: string | null;
+    violations: PolicyViolation[];
+    passed: string[];
+}
+interface CheckReport {
+    passed: boolean;
+    repos: RepoCheckResult[];
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        violations: number;
+    };
+}
+interface CategoryResult {
+    path: string;
+    category: string | null;
+    rules: string[];
+}
+interface PolicyCategoryConfig {
+    paths: string[];
+    rules: string[];
+}
+interface PolicyRuleConfig {
+    description: string;
+    severity: PolicySeverity;
+    config?: Record<string, unknown>;
+}
+interface PolicyConfig {
+    categories: Record<string, PolicyCategoryConfig>;
+    rules: Record<string, PolicyRuleConfig>;
+}
+interface ApiSnapshot {
+    packageName: string;
+    version: string;
+    symbols: string[];
+    extractedAt: string;
+}
+
+declare const PolicyRuleConfigSchema: z.ZodObject<{
+    description: z.ZodString;
+    severity: z.ZodEnum<["error", "warning"]>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    severity: "error" | "warning";
+    config?: Record<string, unknown> | undefined;
+}, {
+    description: string;
+    severity: "error" | "warning";
+    config?: Record<string, unknown> | undefined;
+}>;
+declare const PolicyCategoryConfigSchema: z.ZodObject<{
+    paths: z.ZodArray<z.ZodString, "many">;
+    rules: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    paths: string[];
+    rules: string[];
+}, {
+    paths: string[];
+    rules: string[];
+}>;
+declare const PolicyConfigSchema: z.ZodObject<{
+    categories: z.ZodRecord<z.ZodString, z.ZodObject<{
+        paths: z.ZodArray<z.ZodString, "many">;
+        rules: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        paths: string[];
+        rules: string[];
+    }, {
+        paths: string[];
+        rules: string[];
+    }>>;
+    rules: z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodString;
+        severity: z.ZodEnum<["error", "warning"]>;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        severity: "error" | "warning";
+        config?: Record<string, unknown> | undefined;
+    }, {
+        description: string;
+        severity: "error" | "warning";
+        config?: Record<string, unknown> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    rules: Record<string, {
+        description: string;
+        severity: "error" | "warning";
+        config?: Record<string, unknown> | undefined;
+    }>;
+    categories: Record<string, {
+        paths: string[];
+        rules: string[];
+    }>;
+}, {
+    rules: Record<string, {
+        description: string;
+        severity: "error" | "warning";
+        config?: Record<string, unknown> | undefined;
+    }>;
+    categories: Record<string, {
+        paths: string[];
+        rules: string[];
+    }>;
+}>;
+type PolicyConfigInput = z.input<typeof PolicyConfigSchema>;
+
+/**
+ * Canonical error codes for every policy violation type.
+ *
+ * Attach `code` to a `PolicyViolation` to enable programmatic discrimination
+ * of violation kinds without parsing free-form message strings.
+ *
+ * All codes share the `POLICY_` prefix so they are unambiguous when mixed
+ * with error codes from other subsystems.
+ */
+declare const PolicyErrorCode: {
+    /**
+     * A package depends on another package that belongs to a category outside
+     * the set of categories permitted for the depending package's own category.
+     * Produced by the `boundary-check` rule.
+     */
+    readonly BOUNDARY_VIOLATION: "POLICY_BOUNDARY_VIOLATION";
+    /**
+     * A plugin package imports an internal platform package directly instead of
+     * going through `@kb-labs/sdk`. Plugin packages must restrict their
+     * `@kb-labs/*` dependencies exclusively to `@kb-labs/sdk`.
+     * Produced by the `sdk-only-deps` rule.
+     */
+    readonly SDK_ONLY_DEP_VIOLATION: "POLICY_SDK_ONLY_DEP_VIOLATION";
+    /**
+     * The local `package.json` version is lower than the version already
+     * published to the npm registry. Published versions may never be decreased.
+     * Produced by the `no-rollback` rule.
+     */
+    readonly VERSION_ROLLBACK: "POLICY_VERSION_ROLLBACK";
+    /**
+     * One or more previously exported public symbols have been removed without
+     * a corresponding major-version bump, constituting a breaking API change.
+     * Produced by the `api-compat-check` / `no-breaking-without-major` rules.
+     */
+    readonly API_BREAKING_CHANGE: "POLICY_API_BREAKING_CHANGE";
+    /**
+     * A policy configuration references a rule name that has no registered
+     * check implementation. The rule will be skipped at runtime.
+     * Produced by the policy runner when an unknown rule key is encountered.
+     */
+    readonly UNKNOWN_RULE: "POLICY_UNKNOWN_RULE";
+};
+/**
+ * Union type of all valid `PolicyErrorCode` string values.
+ * Use this as the type for `PolicyViolation.code`.
+ */
+type PolicyErrorCode = (typeof PolicyErrorCode)[keyof typeof PolicyErrorCode];
+/**
+ * Human-readable descriptions for each `PolicyErrorCode`.
+ *
+ * These are intended as stable reference messages for documentation,
+ * tooling output, and IDE integrations. Individual violations also carry
+ * a context-specific `message` and optional `detail` field on the
+ * `PolicyViolation` object.
+ */
+declare const POLICY_ERROR_MESSAGES: Readonly<Record<PolicyErrorCode, string>>;
+/**
+ * Returns the stable descriptive message for a given `PolicyErrorCode`.
+ *
+ * @example
+ * ```ts
+ * const msg = getPolicyErrorMessage(PolicyErrorCode.BOUNDARY_VIOLATION);
+ * // "A package depends on another package outside its allowed category boundaries. …"
+ * ```
+ */
+declare function getPolicyErrorMessage(code: PolicyErrorCode): string;
+
+/**
+ * Options that control which parts of a {@link PolicyViolation} are included
+ * in the formatted string.
+ */
+interface FormatViolationOptions {
+    /**
+     * Include the `file` field as a path hint when it is present.
+     * @default true
+     */
+    includeFile?: boolean;
+    /**
+     * Include the `detail` field as an indented continuation line when present.
+     * @default true
+     */
+    includeDetail?: boolean;
+    /**
+     * Include the `package` field as a parenthetical suffix on the first line
+     * when it is present.
+     * @default false
+     */
+    includePackage?: boolean;
+}
+/**
+ * Formats a single {@link PolicyViolation} into a human-readable string that
+ * mirrors the canonical CLI output produced by `policy:check`.
+ *
+ * The returned string is **never** terminated with a newline so callers can
+ * join multiple violations however they like (e.g. `'\n'` for terminal output,
+ * `'<br>'` for HTML).
+ *
+ * Layout (each line only emitted when the corresponding field is present and
+ * its option is enabled):
+ *
+ * ```
+ * [severity] rule — message (package)
+ *   → detail
+ *   @ file
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { formatViolation } from '@kb-labs/policy-contracts';
+ *
+ * const line = formatViolation(violation);
+ * // "[error] boundary-check — pkg-a depends on pkg-b (category: plugins)"
+ *
+ * const withDetail = formatViolation(violation, { includeDetail: true });
+ * // "[error] boundary-check — pkg-a depends on pkg-b (category: plugins)\n  → Category "platform" may only depend on: shared"
+ * ```
+ */
+declare function formatViolation(violation: PolicyViolation, options?: FormatViolationOptions): string;
+
+/**
+ * A mapping from rule identifier to the total number of violations produced
+ * by that rule across all inputs passed to {@link getViolationSummary}.
+ *
+ * Only rules that produced **at least one** violation appear as keys; rules
+ * that passed cleanly are omitted so callers can use a simple
+ * `Object.keys(summary).length === 0` emptiness check.
+ *
+ * @example
+ * ```ts
+ * const summary: ViolationSummary = { 'sdk-only-deps': 3, 'boundary-check': 1 };
+ * ```
+ */
+type ViolationSummary = Record<string, number>;
+/**
+ * Counts the number of violations per rule across a flat array of
+ * {@link PolicyViolation} objects.
+ *
+ * @example
+ * ```ts
+ * import { getViolationSummary } from '@kb-labs/policy-contracts';
+ *
+ * const violations: PolicyViolation[] = [
+ *   { rule: 'sdk-only-deps', severity: 'error',   message: 'pkg-a imports core' },
+ *   { rule: 'boundary-check', severity: 'warning', message: 'pkg-b depends on plugins' },
+ *   { rule: 'sdk-only-deps', severity: 'error',   message: 'pkg-c imports core' },
+ * ];
+ *
+ * getViolationSummary(violations);
+ * // → { 'sdk-only-deps': 2, 'boundary-check': 1 }
+ * ```
+ */
+declare function getViolationSummary(violations: PolicyViolation[]): ViolationSummary;
+/**
+ * Counts the number of violations per rule for a single
+ * {@link RepoCheckResult}.
+ *
+ * @example
+ * ```ts
+ * import { getViolationSummary } from '@kb-labs/policy-contracts';
+ *
+ * getViolationSummary(repoResult);
+ * // → { 'boundary-check': 3 }
+ * ```
+ */
+declare function getViolationSummary(result: RepoCheckResult): ViolationSummary;
+/**
+ * Counts the number of violations per rule across **all** repos in a
+ * {@link CheckReport}, aggregating results from every
+ * `report.repos[n].violations` array.
+ *
+ * @example
+ * ```ts
+ * import { getViolationSummary } from '@kb-labs/policy-contracts';
+ *
+ * getViolationSummary(report);
+ * // → { 'sdk-only-deps': 5, 'no-rollback': 2 }
+ * ```
+ */
+declare function getViolationSummary(report: CheckReport): ViolationSummary;
+/**
+ * Returns `true` when every repo in the report passed all policy rules
+ * (i.e. `report.passed === true`), `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * import { isPolicyPassing } from '@kb-labs/policy-contracts';
+ *
+ * if (!isPolicyPassing(report)) {
+ *   process.exit(1);
+ * }
+ * ```
+ */
+declare function isPolicyPassing(report: CheckReport): boolean;
+/**
+ * Merges multiple {@link CheckReport} objects into a single consolidated report.
+ *
+ * All `repos` arrays are concatenated in input order. The `summary` counters
+ * (`total`, `passed`, `failed`, `violations`) are recomputed from the merged
+ * repo list. The top-level `passed` flag is `true` only when the merged result
+ * has **zero** violations.
+ *
+ * Repos that share the same `path` across different input reports are kept as
+ * separate entries (concatenation, not deduplication). Callers who need
+ * dedup-by-path can post-process the returned `repos` array.
+ *
+ * @example
+ * ```ts
+ * import { mergeViolations } from '@kb-labs/policy-contracts';
+ *
+ * const combined = mergeViolations([reportA, reportB]);
+ * // combined.repos === [...reportA.repos, ...reportB.repos]
+ * // combined.passed === (combined.summary.violations === 0)
+ * ```
+ */
+declare function mergeViolations(reports: CheckReport[]): CheckReport;
+
+export { type ApiSnapshot, type CategoryResult, type CheckReport, type FormatViolationOptions, POLICY_ERROR_MESSAGES, type PolicyCategoryConfig, PolicyCategoryConfigSchema, type PolicyConfig, type PolicyConfigInput, PolicyConfigSchema, PolicyErrorCode, type PolicyRuleConfig, PolicyRuleConfigSchema, type PolicySeverity, type PolicyViolation, type RepoCheckResult, type ViolationSummary, formatViolation, getPolicyErrorMessage, getViolationSummary, isPolicyPassing, mergeViolations };

package/dist/index.js

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+
+// src/schema.ts
+var PolicyRuleConfigSchema = z.object({
+  description: z.string(),
+  severity: z.enum(["error", "warning"]),
+  config: z.record(z.unknown()).optional()
+});
+var PolicyCategoryConfigSchema = z.object({
+  paths: z.array(z.string()),
+  rules: z.array(z.string())
+});
+var PolicyConfigSchema = z.object({
+  categories: z.record(PolicyCategoryConfigSchema),
+  rules: z.record(PolicyRuleConfigSchema)
+});
+
+// src/error-codes.ts
+var PolicyErrorCode = {
+  /**
+   * A package depends on another package that belongs to a category outside
+   * the set of categories permitted for the depending package's own category.
+   * Produced by the `boundary-check` rule.
+   */
+  BOUNDARY_VIOLATION: "POLICY_BOUNDARY_VIOLATION",
+  /**
+   * A plugin package imports an internal platform package directly instead of
+   * going through `@kb-labs/sdk`. Plugin packages must restrict their
+   * `@kb-labs/*` dependencies exclusively to `@kb-labs/sdk`.
+   * Produced by the `sdk-only-deps` rule.
+   */
+  SDK_ONLY_DEP_VIOLATION: "POLICY_SDK_ONLY_DEP_VIOLATION",
+  /**
+   * The local `package.json` version is lower than the version already
+   * published to the npm registry. Published versions may never be decreased.
+   * Produced by the `no-rollback` rule.
+   */
+  VERSION_ROLLBACK: "POLICY_VERSION_ROLLBACK",
+  /**
+   * One or more previously exported public symbols have been removed without
+   * a corresponding major-version bump, constituting a breaking API change.
+   * Produced by the `api-compat-check` / `no-breaking-without-major` rules.
+   */
+  API_BREAKING_CHANGE: "POLICY_API_BREAKING_CHANGE",
+  /**
+   * A policy configuration references a rule name that has no registered
+   * check implementation. The rule will be skipped at runtime.
+   * Produced by the policy runner when an unknown rule key is encountered.
+   */
+  UNKNOWN_RULE: "POLICY_UNKNOWN_RULE"
+};
+var POLICY_ERROR_MESSAGES = {
+  [PolicyErrorCode.BOUNDARY_VIOLATION]: "A package depends on another package outside its allowed category boundaries. Each workspace category may only import packages from the explicitly permitted categories listed in the policy configuration.",
+  [PolicyErrorCode.SDK_ONLY_DEP_VIOLATION]: "A plugin package imports an internal platform package directly instead of going through @kb-labs/sdk. Plugin packages must limit their @kb-labs/* dependencies to @kb-labs/sdk only. Move required types and utilities to the SDK or use its re-exports.",
+  [PolicyErrorCode.VERSION_ROLLBACK]: "The local package.json version is lower than the version already published to the npm registry. Versions may never be decreased once published \u2014 restore the version to the published value or release a higher version.",
+  [PolicyErrorCode.API_BREAKING_CHANGE]: "One or more previously exported symbols have been removed without a corresponding major-version bump. Either restore the removed symbols to preserve backward compatibility, or increment the major version before removing them.",
+  [PolicyErrorCode.UNKNOWN_RULE]: 'A policy rule reference was encountered that has no registered check implementation. Verify that the rule name in the policy configuration exactly matches a supported rule identifier (e.g. "sdk-only-deps", "boundary-check", "no-rollback", "api-compat-check").'
+};
+function getPolicyErrorMessage(code) {
+  return POLICY_ERROR_MESSAGES[code];
+}
+
+// src/format.ts
+function formatViolation(violation, options = {}) {
+  const { includeFile = true, includeDetail = true, includePackage = false } = options;
+  const packageSuffix = includePackage && violation.package ? ` (${violation.package})` : "";
+  const firstLine = `[${violation.severity}] ${violation.rule} \u2014 ${violation.message}${packageSuffix}`;
+  const lines = [firstLine];
+  if (includeDetail && violation.detail) {
+    lines.push(`  \u2192 ${violation.detail}`);
+  }
+  if (includeFile && violation.file) {
+    lines.push(`  @ ${violation.file}`);
+  }
+  return lines.join("\n");
+}
+
+// src/helpers.ts
+function getViolationSummary(input) {
+  let violations;
+  if (Array.isArray(input)) {
+    violations = input;
+  } else if ("repos" in input) {
+    violations = input.repos.flatMap((r) => r.violations);
+  } else {
+    violations = input.violations;
+  }
+  const summary = {};
+  for (const v of violations) {
+    summary[v.rule] = (summary[v.rule] ?? 0) + 1;
+  }
+  return summary;
+}
+function isPolicyPassing(report) {
+  return report.passed;
+}
+function mergeViolations(reports) {
+  const repos = reports.flatMap((r) => r.repos);
+  const total = repos.length;
+  const failed = repos.filter((r) => r.violations.length > 0).length;
+  const passedRepos = total - failed;
+  const violations = repos.reduce((acc, r) => acc + r.violations.length, 0);
+  return {
+    passed: violations === 0,
+    repos,
+    summary: { total, passed: passedRepos, failed, violations }
+  };
+}
+
+export { POLICY_ERROR_MESSAGES, PolicyCategoryConfigSchema, PolicyConfigSchema, PolicyErrorCode, PolicyRuleConfigSchema, formatViolation, getPolicyErrorMessage, getViolationSummary, isPolicyPassing, mergeViolations };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/error-codes.ts","../src/format.ts","../src/helpers.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { z } from 'zod';\n\nexport const PolicyRuleConfigSchema = z.object({\n  description: z.string(),\n  severity: z.enum(['error', 'warning']),\n  config: z.record(z.unknown()).optional(),\n});\n\nexport const PolicyCategoryConfigSchema = z.object({\n  paths: z.array(z.string()),\n  rules: z.array(z.string()),\n});\n\nexport const PolicyConfigSchema = z.object({\n  categories: z.record(PolicyCategoryConfigSchema),\n  rules: z.record(PolicyRuleConfigSchema),\n});\n\nexport type PolicyConfigInput = z.input<typeof PolicyConfigSchema>;\n","/**\n * Canonical error codes for every policy violation type.\n *\n * Attach `code` to a `PolicyViolation` to enable programmatic discrimination\n * of violation kinds without parsing free-form message strings.\n *\n * All codes share the `POLICY_` prefix so they are unambiguous when mixed\n * with error codes from other subsystems.\n */\nexport const PolicyErrorCode = {\n  /**\n   * A package depends on another package that belongs to a category outside\n   * the set of categories permitted for the depending package's own category.\n   * Produced by the `boundary-check` rule.\n   */\n  BOUNDARY_VIOLATION: 'POLICY_BOUNDARY_VIOLATION',\n\n  /**\n   * A plugin package imports an internal platform package directly instead of\n   * going through `@kb-labs/sdk`. Plugin packages must restrict their\n   * `@kb-labs/*` dependencies exclusively to `@kb-labs/sdk`.\n   * Produced by the `sdk-only-deps` rule.\n   */\n  SDK_ONLY_DEP_VIOLATION: 'POLICY_SDK_ONLY_DEP_VIOLATION',\n\n  /**\n   * The local `package.json` version is lower than the version already\n   * published to the npm registry. Published versions may never be decreased.\n   * Produced by the `no-rollback` rule.\n   */\n  VERSION_ROLLBACK: 'POLICY_VERSION_ROLLBACK',\n\n  /**\n   * One or more previously exported public symbols have been removed without\n   * a corresponding major-version bump, constituting a breaking API change.\n   * Produced by the `api-compat-check` / `no-breaking-without-major` rules.\n   */\n  API_BREAKING_CHANGE: 'POLICY_API_BREAKING_CHANGE',\n\n  /**\n   * A policy configuration references a rule name that has no registered\n   * check implementation. The rule will be skipped at runtime.\n   * Produced by the policy runner when an unknown rule key is encountered.\n   */\n  UNKNOWN_RULE: 'POLICY_UNKNOWN_RULE',\n} as const;\n\n/**\n * Union type of all valid `PolicyErrorCode` string values.\n * Use this as the type for `PolicyViolation.code`.\n */\nexport type PolicyErrorCode = (typeof PolicyErrorCode)[keyof typeof PolicyErrorCode];\n\n/**\n * Human-readable descriptions for each `PolicyErrorCode`.\n *\n * These are intended as stable reference messages for documentation,\n * tooling output, and IDE integrations. Individual violations also carry\n * a context-specific `message` and optional `detail` field on the\n * `PolicyViolation` object.\n */\nexport const POLICY_ERROR_MESSAGES: Readonly<Record<PolicyErrorCode, string>> = {\n  [PolicyErrorCode.BOUNDARY_VIOLATION]:\n    'A package depends on another package outside its allowed category boundaries. ' +\n    'Each workspace category may only import packages from the explicitly permitted categories ' +\n    'listed in the policy configuration.',\n\n  [PolicyErrorCode.SDK_ONLY_DEP_VIOLATION]:\n    'A plugin package imports an internal platform package directly instead of going through ' +\n    '@kb-labs/sdk. Plugin packages must limit their @kb-labs/* dependencies to @kb-labs/sdk only. ' +\n    'Move required types and utilities to the SDK or use its re-exports.',\n\n  [PolicyErrorCode.VERSION_ROLLBACK]:\n    'The local package.json version is lower than the version already published to the npm registry. ' +\n    'Versions may never be decreased once published — restore the version to the published value or ' +\n    'release a higher version.',\n\n  [PolicyErrorCode.API_BREAKING_CHANGE]:\n    'One or more previously exported symbols have been removed without a corresponding major-version ' +\n    'bump. Either restore the removed symbols to preserve backward compatibility, or increment the ' +\n    'major version before removing them.',\n\n  [PolicyErrorCode.UNKNOWN_RULE]:\n    'A policy rule reference was encountered that has no registered check implementation. ' +\n    'Verify that the rule name in the policy configuration exactly matches a supported rule ' +\n    'identifier (e.g. \"sdk-only-deps\", \"boundary-check\", \"no-rollback\", \"api-compat-check\").',\n};\n\n/**\n * Returns the stable descriptive message for a given `PolicyErrorCode`.\n *\n * @example\n * ```ts\n * const msg = getPolicyErrorMessage(PolicyErrorCode.BOUNDARY_VIOLATION);\n * // \"A package depends on another package outside its allowed category boundaries. …\"\n * ```\n */\nexport function getPolicyErrorMessage(code: PolicyErrorCode): string {\n  return POLICY_ERROR_MESSAGES[code];\n}\n","import type { PolicyViolation } from './types.js';\n\n/**\n * Options that control which parts of a {@link PolicyViolation} are included\n * in the formatted string.\n */\nexport interface FormatViolationOptions {\n  /**\n   * Include the `file` field as a path hint when it is present.\n   * @default true\n   */\n  includeFile?: boolean;\n\n  /**\n   * Include the `detail` field as an indented continuation line when present.\n   * @default true\n   */\n  includeDetail?: boolean;\n\n  /**\n   * Include the `package` field as a parenthetical suffix on the first line\n   * when it is present.\n   * @default false\n   */\n  includePackage?: boolean;\n}\n\n/**\n * Formats a single {@link PolicyViolation} into a human-readable string that\n * mirrors the canonical CLI output produced by `policy:check`.\n *\n * The returned string is **never** terminated with a newline so callers can\n * join multiple violations however they like (e.g. `'\\n'` for terminal output,\n * `'<br>'` for HTML).\n *\n * Layout (each line only emitted when the corresponding field is present and\n * its option is enabled):\n *\n * ```\n * [severity] rule — message (package)\n *   → detail\n *   @ file\n * ```\n *\n * @example\n * ```ts\n * import { formatViolation } from '@kb-labs/policy-contracts';\n *\n * const line = formatViolation(violation);\n * // \"[error] boundary-check — pkg-a depends on pkg-b (category: plugins)\"\n *\n * const withDetail = formatViolation(violation, { includeDetail: true });\n * // \"[error] boundary-check — pkg-a depends on pkg-b (category: plugins)\\n  → Category \"platform\" may only depend on: shared\"\n * ```\n */\nexport function formatViolation(\n  violation: PolicyViolation,\n  options: FormatViolationOptions = {},\n): string {\n  const { includeFile = true, includeDetail = true, includePackage = false } = options;\n\n  const packageSuffix =\n    includePackage && violation.package ? ` (${violation.package})` : '';\n\n  const firstLine = `[${violation.severity}] ${violation.rule} — ${violation.message}${packageSuffix}`;\n\n  const lines: string[] = [firstLine];\n\n  if (includeDetail && violation.detail) {\n    lines.push(`  → ${violation.detail}`);\n  }\n\n  if (includeFile && violation.file) {\n    lines.push(`  @ ${violation.file}`);\n  }\n\n  return lines.join('\\n');\n}\n","import type { CheckReport, PolicyViolation, RepoCheckResult } from './types.js';\n\n/**\n * A mapping from rule identifier to the total number of violations produced\n * by that rule across all inputs passed to {@link getViolationSummary}.\n *\n * Only rules that produced **at least one** violation appear as keys; rules\n * that passed cleanly are omitted so callers can use a simple\n * `Object.keys(summary).length === 0` emptiness check.\n *\n * @example\n * ```ts\n * const summary: ViolationSummary = { 'sdk-only-deps': 3, 'boundary-check': 1 };\n * ```\n */\nexport type ViolationSummary = Record<string, number>;\n\n/**\n * Counts the number of violations per rule across a flat array of\n * {@link PolicyViolation} objects.\n *\n * @example\n * ```ts\n * import { getViolationSummary } from '@kb-labs/policy-contracts';\n *\n * const violations: PolicyViolation[] = [\n *   { rule: 'sdk-only-deps', severity: 'error',   message: 'pkg-a imports core' },\n *   { rule: 'boundary-check', severity: 'warning', message: 'pkg-b depends on plugins' },\n *   { rule: 'sdk-only-deps', severity: 'error',   message: 'pkg-c imports core' },\n * ];\n *\n * getViolationSummary(violations);\n * // → { 'sdk-only-deps': 2, 'boundary-check': 1 }\n * ```\n */\nexport function getViolationSummary(violations: PolicyViolation[]): ViolationSummary;\n\n/**\n * Counts the number of violations per rule for a single\n * {@link RepoCheckResult}.\n *\n * @example\n * ```ts\n * import { getViolationSummary } from '@kb-labs/policy-contracts';\n *\n * getViolationSummary(repoResult);\n * // → { 'boundary-check': 3 }\n * ```\n */\nexport function getViolationSummary(result: RepoCheckResult): ViolationSummary;\n\n/**\n * Counts the number of violations per rule across **all** repos in a\n * {@link CheckReport}, aggregating results from every\n * `report.repos[n].violations` array.\n *\n * @example\n * ```ts\n * import { getViolationSummary } from '@kb-labs/policy-contracts';\n *\n * getViolationSummary(report);\n * // → { 'sdk-only-deps': 5, 'no-rollback': 2 }\n * ```\n */\nexport function getViolationSummary(report: CheckReport): ViolationSummary;\n\nexport function getViolationSummary(\n  input: PolicyViolation[] | RepoCheckResult | CheckReport,\n): ViolationSummary {\n  let violations: PolicyViolation[];\n\n  if (Array.isArray(input)) {\n    // Overload 1: flat PolicyViolation[]\n    violations = input;\n  } else if ('repos' in input) {\n    // Overload 3: CheckReport — `repos` is unique to CheckReport; RepoCheckResult does not have it\n    violations = (input as CheckReport).repos.flatMap((r) => r.violations);\n  } else {\n    // Overload 2: RepoCheckResult\n    violations = (input as RepoCheckResult).violations;\n  }\n\n  const summary: ViolationSummary = {};\n  for (const v of violations) {\n    summary[v.rule] = (summary[v.rule] ?? 0) + 1;\n  }\n  return summary;\n}\n\n\n/**\n * Returns `true` when every repo in the report passed all policy rules\n * (i.e. `report.passed === true`), `false` otherwise.\n *\n * @example\n * ```ts\n * import { isPolicyPassing } from '@kb-labs/policy-contracts';\n *\n * if (!isPolicyPassing(report)) {\n *   process.exit(1);\n * }\n * ```\n */\nexport function isPolicyPassing(report: CheckReport): boolean {\n  return report.passed;\n}\n\n\n/**\n * Merges multiple {@link CheckReport} objects into a single consolidated report.\n *\n * All `repos` arrays are concatenated in input order. The `summary` counters\n * (`total`, `passed`, `failed`, `violations`) are recomputed from the merged\n * repo list. The top-level `passed` flag is `true` only when the merged result\n * has **zero** violations.\n *\n * Repos that share the same `path` across different input reports are kept as\n * separate entries (concatenation, not deduplication). Callers who need\n * dedup-by-path can post-process the returned `repos` array.\n *\n * @example\n * ```ts\n * import { mergeViolations } from '@kb-labs/policy-contracts';\n *\n * const combined = mergeViolations([reportA, reportB]);\n * // combined.repos === [...reportA.repos, ...reportB.repos]\n * // combined.passed === (combined.summary.violations === 0)\n * ```\n */\nexport function mergeViolations(reports: CheckReport[]): CheckReport {\n  const repos = reports.flatMap((r) => r.repos);\n  const total = repos.length;\n  const failed = repos.filter((r) => r.violations.length > 0).length;\n  const passedRepos = total - failed;\n  const violations = repos.reduce((acc, r) => acc + r.violations.length, 0);\n  return {\n    passed: violations === 0,\n    repos,\n    summary: { total, passed: passedRepos, failed, violations },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@kb-labs/policy-contracts",
+  "version": "0.5.0",
+  "type": "module",
+  "description": "Types, interfaces, and schemas for the KB Labs policy plugin.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./dist/*": "./dist/*"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@kb-labs/devkit": "link:../../../../infra/kb-labs-devkit",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}