@kici-dev/compiler 0.1.26 → 0.2.0

package/dist/test-runner/payload-builder.js

@@ -147,7 +147,8 @@ async function buildEventPayload(eventArg, options) {
 		payload: mergedPayload,
 		targetBranch,
 		sourceBranch,
-		changedFiles: options.files ?? []
+		changedFiles: options.files ?? [],
+		changedFilesStatus: options.changedFilesStatus ?? "fetched"
 	};
 }
 /**
@@ -157,6 +158,7 @@ function isInternalEventType(eventType) {
 	return [
 		"kici_event",
 		"workflow_complete",
+		"workflows_failed_batch",
 		"job_complete",
 		"generic_webhook",
 		"schedule",
@@ -182,6 +184,12 @@ async function buildInternalEventPayload(eventType, options) {
 				status: eventType.status
 			};
 			break;
+		case "workflows_failed_batch":
+			payload = {
+				total: 0,
+				runs: []
+			};
+			break;
 		case "job_complete":
 			payload = {
 				workflowName: eventType.workflowName,
@@ -207,7 +215,8 @@ async function buildInternalEventPayload(eventType, options) {
 		action: void 0,
 		payload,
 		targetBranch: "main",
-		changedFiles: options.files ?? []
+		changedFiles: options.files ?? [],
+		changedFilesStatus: options.changedFilesStatus ?? "fetched"
 	};
 }
 //#endregion

package/dist/test-runner/rule-evaluator.d.ts

@@ -1,9 +1,13 @@
-import type { Rule, RuleContext, EventPayload } from '@kici-dev/sdk';
+import type { Rule, RuleContext, CreateRuleContextInput } from '@kici-dev/sdk';
 import type { RuleEvaluationResult } from '@kici-dev/sdk';
 /**
- * Create RuleContext for rule evaluation.
+ * Create a RuleContext for `kici test` rule evaluation. Delegates to the shared
+ * SDK factory (single source of truth), defaulting `env` to the process
+ * environment — the test-runner exposes the developer's real env to rules — and
+ * `changedFilesStatus` to `'fetched'` so an author-supplied (or empty) test
+ * changeset is a genuine diff and `ctx.changedFiles` never throws.
  */
-export declare function createRuleContext(event: EventPayload, changedFiles?: string[], dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>): RuleContext;
+export declare function createRuleContext(input: CreateRuleContextInput): RuleContext;
 /**
  * Evaluate rules with formatting output.
  * Wraps the SDK's evaluateRules() with a callback that logs each rule result.

package/dist/test-runner/rule-evaluator.js

@@ -1,21 +1,22 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { formatter } from "./output-formatter.js";
-import { evaluateRules } from "@kici-dev/sdk";
+import { createRuleContext as createRuleContext$1, evaluateRules } from "@kici-dev/sdk";
 import { initZx } from "@kici-dev/core";
-import { $ } from "zx";
 //#region src/test-runner/rule-evaluator.ts
 initZx();
 /**
-* Create RuleContext for rule evaluation.
+* Create a RuleContext for `kici test` rule evaluation. Delegates to the shared
+* SDK factory (single source of truth), defaulting `env` to the process
+* environment — the test-runner exposes the developer's real env to rules — and
+* `changedFilesStatus` to `'fetched'` so an author-supplied (or empty) test
+* changeset is a genuine diff and `ctx.changedFiles` never throws.
 */
-function createRuleContext(event, changedFiles = [], dispatchInputs = {}) {
-	return {
-		event,
-		changedFiles,
-		env: { ...process.env },
-		dispatchInputs,
-		$
-	};
+function createRuleContext(input) {
+	return createRuleContext$1({
+		...input,
+		env: input.env ?? { ...process.env },
+		changedFilesStatus: input.changedFilesStatus ?? "fetched"
+	});
 }
 /**
 * Evaluate rules with formatting output.
@@ -23,7 +24,7 @@ function createRuleContext(event, changedFiles = [], dispatchInputs = {}) {
 */
 async function evaluateRulesWithFormatting(rules, context, jobName) {
 	return evaluateRules(rules, context, jobName, (result) => {
-		formatter.logRuleResult(jobName, result.label, result.passed);
+		formatter.logRuleResult(jobName, result);
 	});
 }
 //#endregion

package/dist/{local-executor → test-runner}/runs-on-display.js

@@ -1,5 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
-//#region src/local-executor/runs-on-display.ts
+//#region src/test-runner/runs-on-display.ts
 /** Render one selector element (string label or RegExp) for the local display string. */
 function runsOnElementString(el) {
 	return el instanceof RegExp ? el.toString() : el;

package/dist/test-runner/step-context.d.ts

@@ -1,15 +1,33 @@
 import type { StepContext, WorkflowInfo, JobInfo, MatrixValues } from '@kici-dev/sdk';
+/** Handle returned by {@link createStepContext}. */
+export interface LocalStepContext {
+    /** The built step context, threaded into every step of the job. */
+    ctx: StepContext;
+    /**
+     * Drain the job's temp scope (and secrets state). Call once at job end —
+     * success, failure, or throw — to reclaim every `ctx.mktemp`/`ctx.mktempFile`
+     * allocation the job made. Delegates to the shared builder's `dispose`.
+     */
+    dispose: () => Promise<void>;
+}
 /**
  * Create a step context for local test execution.
  *
- * `repoRoot` pins `ctx.$` to the workflow's repository root so steps running
- * via local-dispatch behave the same as on the agent path (see
+ * `repoRoot` pins `ctx.$` to the workflow's repository root so steps running via
+ * local-dispatch behave the same as on the agent path (see
  * `packages/agent/src/execution/sandbox/workflow-runner.ts`). Without this,
- * `ctx.$` would inherit `process.cwd()` — i.e. wherever the user invoked
- * `kici` — which silently breaks any step that uses relative paths.
+ * `ctx.$` would inherit `process.cwd()` — i.e. wherever the user invoked `kici`
+ * — which silently breaks any step that uses relative paths.
+ *
+ * This is a thin adapter over the shared `@kici-dev/sdk/testing` builder — the
+ * single source of truth for constructing a test step context — supplying the
+ * local runner's formatter-backed logger. The shared builder owns the
+ * job-scoped temp allocator backing `ctx.mktemp`/`ctx.mktempFile`; the returned
+ * `dispose` surfaces its drain so the caller (`executeJob`) can reclaim the
+ * job's temp dirs at job end rather than only via the exit backstop.
  */
 export declare function createStepContext(workflowInfo: WorkflowInfo, jobInfo: JobInfo, repoRoot: string, inputs?: Record<string, unknown>, matrix?: MatrixValues, testSecrets?: {
     flat: Record<string, string>;
     contexts: Record<string, Record<string, string>>;
-}, environment?: string, rawPayload?: Record<string, unknown>, provider?: string, dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>, signal?: AbortSignal): StepContext;
+}, context?: string, rawPayload?: Record<string, unknown>, provider?: string, dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>, signal?: AbortSignal): LocalStepContext;
 //# sourceMappingURL=step-context.d.ts.map

package/dist/test-runner/step-context.js

@@ -1,15 +1,9 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { formatter } from "./output-formatter.js";
-import { join } from "node:path";
-import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { createStepSecrets, resolveJobOutputs, resolveStepOutputs } from "@kici-dev/sdk";
-import { initZx } from "@kici-dev/core";
-import { tmpdir } from "node:os";
-import { $ } from "zx";
+import { createTestStepContext } from "@kici-dev/sdk/testing";
 //#region src/test-runner/step-context.ts
-initZx();
 /**
-* Create a logger that prefixes output with job name.
+* Create a logger that prefixes output with the job name.
 */
 function createTestLogger(jobName) {
 	return {
@@ -36,121 +30,37 @@ function createTestLogger(jobName) {
 /**
 * Create a step context for local test execution.
 *
-* `repoRoot` pins `ctx.$` to the workflow's repository root so steps running
-* via local-dispatch behave the same as on the agent path (see
+* `repoRoot` pins `ctx.$` to the workflow's repository root so steps running via
+* local-dispatch behave the same as on the agent path (see
 * `packages/agent/src/execution/sandbox/workflow-runner.ts`). Without this,
-* `ctx.$` would inherit `process.cwd()` — i.e. wherever the user invoked
-* `kici` — which silently breaks any step that uses relative paths.
+* `ctx.$` would inherit `process.cwd()` — i.e. wherever the user invoked `kici`
+* — which silently breaks any step that uses relative paths.
+*
+* This is a thin adapter over the shared `@kici-dev/sdk/testing` builder — the
+* single source of truth for constructing a test step context — supplying the
+* local runner's formatter-backed logger. The shared builder owns the
+* job-scoped temp allocator backing `ctx.mktemp`/`ctx.mktempFile`; the returned
+* `dispose` surfaces its drain so the caller (`executeJob`) can reclaim the
+* job's temp dirs at job end rather than only via the exit backstop.
 */
-function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix, testSecrets, environment, rawPayload, provider, dispatchInputs = {}, signal = new AbortController().signal) {
-	const flat = testSecrets?.flat ?? {};
-	const namespacedSecrets = testSecrets?.contexts ?? {};
-	const mergedFlat = { ...flat };
-	for (const contextSecrets of Object.values(namespacedSecrets)) Object.assign(mergedFlat, contextSecrets);
-	const env = { ...process.env };
-	const scoped$ = $({ cwd: repoRoot });
-	let tmpdirPath = null;
-	const exposedEnvVars = /* @__PURE__ */ new Set();
-	let mountCounter = 0;
-	let exitHandlerRegistered = false;
-	const onProcessExit = () => {
-		for (const envVar of exposedEnvVars) {
-			delete env[envVar];
-			delete process.env[envVar];
-		}
-		exposedEnvVars.clear();
-		if (tmpdirPath !== null) {
-			try {
-				rmSync(tmpdirPath, {
-					recursive: true,
-					force: true
-				});
-			} catch {}
-			tmpdirPath = null;
-		}
-	};
-	const secretsHandle = createStepSecrets(mergedFlat, env, void 0, {
-		host: {
-			async writeMountedFile(args) {
-				if (tmpdirPath === null) tmpdirPath = mkdtempSync(join(tmpdir(), "kici-secret-files-"));
-				if (!exitHandlerRegistered) {
-					process.once("exit", onProcessExit);
-					exitHandlerRegistered = true;
-				}
-				mountCounter += 1;
-				const filename = args.name ?? `secret-${mountCounter}`;
-				const filePath = join(tmpdirPath, filename);
-				writeFileSync(filePath, args.content);
-				chmodSync(filePath, args.mode);
-				return filePath;
-			},
-			trackExposedEnv(envVar) {
-				exposedEnvVars.add(envVar);
-			}
-		},
-		cleanup: async () => {
-			if (exitHandlerRegistered) {
-				process.off("exit", onProcessExit);
-				exitHandlerRegistered = false;
-			}
-			onProcessExit();
-		}
-	});
-	return {
-		$: scoped$,
-		log: createTestLogger(jobInfo.name),
-		signal,
-		env,
-		setEnv: (key, value) => {
-			env[key] = value;
-			process.env[key] = value;
-		},
-		addPath: (dir) => {
-			const updated = `${dir}:${env.PATH ?? process.env.PATH ?? ""}`;
-			env.PATH = updated;
-			process.env.PATH = updated;
-		},
-		inputs,
-		dispatchInputs,
+function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix, testSecrets, context, rawPayload, provider, dispatchInputs = {}, signal = new AbortController().signal) {
+	const { ctx, dispose } = createTestStepContext({
 		workflow: workflowInfo,
 		job: jobInfo,
-		matrix,
-		isTestRun: false,
-		environment,
-		...rawPayload && { rawPayload },
-		...provider && { provider },
-		secrets: secretsHandle.secrets,
-		emit: async () => {
-			return { deliveryId: "local-test-noop" };
-		},
-		outputsOf: (ref) => {
-			return resolveStepOutputs(ref);
-		},
-		jobOutputs: (ref) => {
-			return resolveJobOutputs(ref);
-		},
-		setSecretOutput: () => {},
-		kici: {
-			infrastructure: { list: () => Promise.resolve({
-				scalers: [],
-				agents: []
-			}) },
-			inventory: {
-				query: () => Promise.resolve([]),
-				get: () => Promise.resolve(null)
-			},
-			oidc: { token: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is not available in the local test runner")) },
-			host: { requestReboot: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.host.requestReboot() is not available in the local test runner")) },
-			bootstrap: {
-				ensureInitRunner: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.bootstrap.ensureInitRunner() is not available in the local test runner")),
-				preBootSend: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.bootstrap.preBootSend() is not available in the local test runner"))
-			}
-		},
-		cache: {
-			restore: async () => ({ hit: false }),
-			save: async () => {}
-		},
-		attestProvenance: () => Promise.reject(/* @__PURE__ */ new Error("ctx.attestProvenance() is not available in the local test runner"))
+		repoRoot,
+		inputs,
+		dispatchInputs,
+		signal,
+		log: createTestLogger(jobInfo.name),
+		secrets: testSecrets,
+		...matrix !== void 0 && { matrix },
+		...context !== void 0 && { context },
+		...rawPayload !== void 0 && { rawPayload },
+		...provider !== void 0 && { provider }
+	});
+	return {
+		ctx,
+		dispose
 	};
 }
 //#endregion

package/dist/types.d.ts

@@ -28,7 +28,9 @@ export interface LockApproval {
     readonly when: 'always' | 'drift';
 }
 /** Schema version - re-exported from engine as single source of truth */
-export declare const SCHEMA_VERSION: 29;
+export declare const SCHEMA_VERSION: 32;
+/** Lock compatibility-window floor - re-exported from engine as single source of truth */
+export declare const BREAKING_FLOOR: 30;
 /**
  * Source file reference with meaningful path.
  * Format: file is relative path from git root, export uses hash syntax.
@@ -229,6 +231,17 @@ export interface LockWorkflowCompleteTrigger {
     readonly status?: readonly string[];
     readonly source?: string;
 }
+/**
+ * Workflows-failed-batch trigger in lock file.
+ * Accumulates failed workflow completions over a window and fires the
+ * subscribing workflow once per window with the batched run list.
+ */
+export interface LockWorkflowsFailedBatchTrigger {
+    readonly _type: 'workflows_failed_batch';
+    readonly accumulateFor: number;
+    readonly name?: string;
+    readonly source?: string;
+}
 /**
  * Job completion trigger in lock file.
  * Matches when a specific job within a workflow finishes execution.
@@ -289,7 +302,7 @@ export interface LockLifecycleTrigger {
     readonly description?: string;
 }
 /** Union of all trigger types */
-export type LockTrigger = LockPrTrigger | LockPushTrigger | LockTagTrigger | LockCommentTrigger | LockReviewTrigger | LockReviewCommentTrigger | LockReleaseTrigger | LockDispatchTrigger | LockCreateTrigger | LockDeleteTrigger | LockStatusTrigger | LockWorkflowRunTrigger | LockForkTrigger | LockStarTrigger | LockWatchTrigger | LockWebhookTrigger | LockKiciEventTrigger | LockWorkflowCompleteTrigger | LockJobCompleteTrigger | LockGenericWebhookTrigger | LockScheduleTrigger | LockLifecycleTrigger;
+export type LockTrigger = LockPrTrigger | LockPushTrigger | LockTagTrigger | LockCommentTrigger | LockReviewTrigger | LockReviewCommentTrigger | LockReleaseTrigger | LockDispatchTrigger | LockCreateTrigger | LockDeleteTrigger | LockStatusTrigger | LockWorkflowRunTrigger | LockForkTrigger | LockStarTrigger | LockWatchTrigger | LockWebhookTrigger | LockKiciEventTrigger | LockWorkflowCompleteTrigger | LockWorkflowsFailedBatchTrigger | LockJobCompleteTrigger | LockGenericWebhookTrigger | LockScheduleTrigger | LockLifecycleTrigger;
 /**
  * Matrix configuration in lock file.
  * Static matrices are expanded at orchestrator, dynamic at agent runtime.
@@ -441,11 +454,11 @@ export interface LockJob {
         env?: Record<string, string>;
     };
     /**
-     * Deployment environments in merge order. Each entry is a static name or inline
+     * Bound contexts in merge order. Each entry is a static name or inline
      * expression (pure function); `dynamic` is set when it is a function resolved at
      * two-phase eval. Later entries override earlier ones on name collisions.
      */
-    readonly environments?: ReadonlyArray<{
+    readonly contexts?: ReadonlyArray<{
         value: string | LockInlineValue;
         dynamic: boolean;
     }>;
@@ -517,12 +530,12 @@ export type LockJobOrFactory = LockJob | LockDynamicJobFn;
 /**
  * Private npm registry declaration in the lock file.
  * Carries URL/scope/secret-reference but NOT the resolved token — the orchestrator
- * resolves the token at dispatch via the per-environment secretResolver path.
+ * resolves the token at dispatch via the per-context secretResolver path.
  */
 export interface LockRegistry {
     readonly url: string;
     readonly scope?: string;
-    /** Qualified secret reference: `<environment>:<secret-name>`. */
+    /** Qualified secret reference: `<context>:<secret-name>`. */
     readonly tokenSecret: string;
     readonly alwaysAuth?: boolean;
 }
@@ -554,7 +567,7 @@ export interface LockWorkflow {
      */
     readonly registries?: readonly LockRegistry[];
     /**
-     * Extra qualified secret refs (`<environment>:<secret-name>`) to project as env vars
+     * Extra qualified secret refs (`<context>:<secret-name>`) to project as env vars
      * on the install subprocess for use with a customer-committed `.kici/.npmrc`.
      */
     readonly installEnv?: readonly string[];
@@ -592,6 +605,12 @@ export interface LockWorkflow {
  */
 export interface LockFile {
     readonly schemaVersion: typeof SCHEMA_VERSION;
+    /**
+     * Newest breaking schema version at emit time (`BREAKING_FLOOR`). Readers
+     * whose own SCHEMA_VERSION is below this must reject the lock. Mirrors the
+     * engine `LockFile.minReaderVersion` field.
+     */
+    readonly minReaderVersion?: number;
     readonly source: LockSource;
     /** SHA-256 hash of the serialized lock file content (excluding this field). Changes only when workflows, triggers, jobs, or bundle hashes change. */
     readonly contentHash: string;

package/dist/types.js

@@ -1,5 +1,5 @@
 import "./rolldown-runtime-ClRpJifh.js";
-import { SCHEMA_VERSION as SCHEMA_VERSION$1 } from "@kici-dev/engine";
+import { BREAKING_FLOOR as BREAKING_FLOOR$1, SCHEMA_VERSION as SCHEMA_VERSION$1 } from "@kici-dev/engine";
 //#region src/types.ts
 /**
 * Lock file schema version 11.
@@ -17,6 +17,8 @@ import { SCHEMA_VERSION as SCHEMA_VERSION$1 } from "@kici-dev/engine";
 */
 /** Schema version - re-exported from engine as single source of truth */
 const SCHEMA_VERSION = SCHEMA_VERSION$1;
+/** Lock compatibility-window floor - re-exported from engine as single source of truth */
+const BREAKING_FLOOR = BREAKING_FLOOR$1;
 /** Type guard distinguishing a parallel group from an ordinary lock step. */
 function isLockParallelStep(entry) {
 	return entry.kind === "parallel";
@@ -34,6 +36,6 @@ function isLockDynamicJobFn(job) {
 	return job._type === "dynamic";
 }
 //#endregion
-export { SCHEMA_VERSION, isLockDynamicJobFn, isLockInlineValue, isLockParallelStep, isLockStaticJob };
+export { BREAKING_FLOOR, SCHEMA_VERSION, isLockDynamicJobFn, isLockInlineValue, isLockParallelStep, isLockStaticJob };
 
 //# sourceMappingURL=types.js.map

package/dist/validation/index.d.ts

@@ -1,3 +1,5 @@
 export { validateConfig } from './validator.js';
 export type { ValidationResult } from './validator.js';
+export { runTypecheck, parseTscOutput } from './typecheck.js';
+export type { TypecheckResult } from './typecheck.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/validation/index.js

@@ -1,3 +1,4 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { validateConfig } from "./validator.js";
-export { validateConfig };
+import { parseTscOutput, runTypecheck } from "./typecheck.js";
+export { parseTscOutput, runTypecheck, validateConfig };

package/dist/validation/typecheck.d.ts

@@ -0,0 +1,28 @@
+import { type CompilerError } from '../errors/index.js';
+/**
+ * Result of the opt-in `tsc --noEmit` type-check pass.
+ *
+ * `ran: false` means the pass was skipped (no `tsconfig.json` — a
+ * JavaScript-only / `--mjs` workspace has no types to check). `ran: true` with
+ * an empty `errors` array means the sources type-check cleanly.
+ */
+export interface TypecheckResult {
+    ran: boolean;
+    errors: CompilerError[];
+}
+/**
+ * Turn `tsc --noEmit --pretty false` output into located `E120` compiler errors.
+ * Handles both located diagnostics (`file(line,col): error TS…`) and global
+ * ones (`error TS…`, e.g. a bad tsconfig). Non-diagnostic noise lines are
+ * ignored. Paths are left as tsc emits them (kiciDir-relative), readable in the
+ * GNU error format.
+ */
+export declare function parseTscOutput(stdout: string): CompilerError[];
+/**
+ * Run an opt-in `tsc --noEmit` type-check over the workflow sources in
+ * `kiciDir`. Skips (returns `ran: false`) when there is no `tsconfig.json`.
+ * Prefers the workspace-local `tsc` binary, falling back to `npx typescript`;
+ * returns a single `E121` when the compiler cannot be resolved.
+ */
+export declare function runTypecheck(kiciDir: string): Promise<TypecheckResult>;
+//# sourceMappingURL=typecheck.d.ts.map

package/dist/validation/typecheck.js

@@ -0,0 +1,110 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { compilerError } from "../errors/formatter.js";
+import "../errors/index.js";
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { $ } from "zx";
+import { initZx } from "@kici-dev/core";
+//#region src/validation/typecheck.ts
+initZx();
+/** `path(line,col): error TSxxxx: message` — a located tsc diagnostic. */
+const TSC_LOCATED_RE = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.+)$/;
+/** `error TSxxxx: message` — a global tsc diagnostic (config errors, etc.). */
+const TSC_GLOBAL_RE = /^error (TS\d+): (.+)$/;
+/**
+* Turn `tsc --noEmit --pretty false` output into located `E120` compiler errors.
+* Handles both located diagnostics (`file(line,col): error TS…`) and global
+* ones (`error TS…`, e.g. a bad tsconfig). Non-diagnostic noise lines are
+* ignored. Paths are left as tsc emits them (kiciDir-relative), readable in the
+* GNU error format.
+*/
+function parseTscOutput(stdout) {
+	const errors = [];
+	for (const raw of stdout.split("\n")) {
+		const line = raw.trim();
+		const located = TSC_LOCATED_RE.exec(line);
+		if (located) {
+			const [, file, lineStr, colStr, tsCode, message] = located;
+			const location = {
+				file,
+				line: parseInt(lineStr, 10),
+				column: parseInt(colStr, 10)
+			};
+			errors.push(compilerError("E120", `${tsCode}: ${message}`, {
+				location,
+				suggestion: "Fix the type error in your workflow source."
+			}));
+			continue;
+		}
+		const global = TSC_GLOBAL_RE.exec(line);
+		if (global) {
+			const [, tsCode, message] = global;
+			errors.push(compilerError("E120", `${tsCode}: ${message}`, { suggestion: "Fix the type error in your workflow source." }));
+		}
+	}
+	return errors;
+}
+/** The E121 "compiler could not be resolved" error. */
+function typecheckUnavailable() {
+	return compilerError("E121", "Type-check unavailable: could not resolve the TypeScript compiler", { suggestion: "Add \"typescript\" to your .kici/package.json devDependencies (kici init scaffolds it), then reinstall." });
+}
+/**
+* Run an opt-in `tsc --noEmit` type-check over the workflow sources in
+* `kiciDir`. Skips (returns `ran: false`) when there is no `tsconfig.json`.
+* Prefers the workspace-local `tsc` binary, falling back to `npx typescript`;
+* returns a single `E121` when the compiler cannot be resolved.
+*/
+async function runTypecheck(kiciDir) {
+	const tsconfigPath = path.join(kiciDir, "tsconfig.json");
+	if (!existsSync(tsconfigPath)) return {
+		ran: false,
+		errors: []
+	};
+	const localBin = path.join(kiciDir, "node_modules", ".bin", "tsc");
+	const usedLocal = existsSync(localBin);
+	const invocation = usedLocal ? [localBin] : [
+		"npx",
+		"--yes",
+		"-p",
+		"typescript",
+		"tsc"
+	];
+	const tscArgs = [
+		"--noEmit",
+		"--pretty",
+		"false",
+		"-p",
+		tsconfigPath
+	];
+	let out;
+	try {
+		out = await $({
+			cwd: kiciDir,
+			nothrow: true
+		})`${invocation} ${tscArgs}`;
+	} catch {
+		return {
+			ran: true,
+			errors: [typecheckUnavailable()]
+		};
+	}
+	const errors = parseTscOutput(out.stdout);
+	if (out.exitCode !== 0 && errors.length === 0) {
+		if (!usedLocal) return {
+			ran: true,
+			errors: [typecheckUnavailable()]
+		};
+		return {
+			ran: true,
+			errors: [compilerError("E120", `type-check failed: ${(out.stderr || out.stdout).trim()}`, { suggestion: "Fix the type error in your workflow source." })]
+		};
+	}
+	return {
+		ran: true,
+		errors
+	};
+}
+//#endregion
+export { parseTscOutput, runTypecheck };
+
+//# sourceMappingURL=typecheck.js.map

package/dist/validation/validator.d.ts

@@ -1,5 +1,5 @@
-import type { Workflow } from '@kici-dev/sdk';
 import { type CompilerError } from '../errors/index.js';
+import type { WorkflowWithSource } from '../types.js';
 /**
  * Validation result - either success or list of errors.
  */
@@ -18,9 +18,14 @@ export type ValidationResult = {
  * 3. Job dependencies are valid (exist, no cycles, no self-refs)
  * 4. Static matrix expansions stay under 256 job limit
  *
- * @param workflows - Array of workflows from config
- * @param configPath - Path for error location reporting
+ * Each error carries the most precise `file:line:column` the data allows: a
+ * job-scoped error anchors to the offending job's first step location (real
+ * file + real line), falling back to the workflow's source file at line 1 when
+ * no step exists; a workflow-scoped error uses the workflow source file (line 1,
+ * since `workflow()` captures no call-site).
+ *
+ * @param workflows - Source-carrying workflows from discovery
  * @returns Validation result with errors if any
  */
-export declare function validateConfig(workflows: Workflow[], configPath: string): ValidationResult;
+export declare function validateConfig(workflows: WorkflowWithSource[]): ValidationResult;
 //# sourceMappingURL=validator.d.ts.map