@gfdelarue/testkit 0.3.0

package/dist/app/doctor/index.js

@@ -0,0 +1 @@
+import p from"path";import{discoverTests as h,loadConfigContext as m}from"../../config/loader/index.js";import{runTestkitTypecheck as k}from"../typecheck/index.js";import{runLintForConfig as v}from"../lint/index.js";export async function runDoctor(e={}){const t=[],r=e.dir?p.resolve(process.cwd(),e.dir):process.cwd(),s=await m({dir:r});t.push({code:"config-load",level:"pass",message:"Loaded testkit config and service config"});const f=await h({dir:r,diagnostics:"report"}),l=b(f,"discovery result"),u=a(l.diagnostics,"discovery result diagnostics"),g=a(l.files,"discovery result files"),n=u.filter(w);t.push({code:"discovery",level:n.length===0?"pass":"fail",message:n.length===0?`Discovered ${String(g.length)} testkit files without diagnostics`:`Discovery reported ${String(n.length)} error diagnostics`,details:n});const i=await v(c(s,"config"),{dir:r});if(t.push({code:"lint",level:i.ok?"pass":"fail",message:i.ok?`No Testkit lint violations across ${String(i.summary.testkitFiles)} suite file(s)`:`Found ${String(i.summary.violations)} Testkit lint violation(s)`,details:i.violations}),e.typecheck!==!1)try{const o=await k({dir:r}),y=a(c(o,"results"),"typecheck results");t.push({code:"typecheck",level:"pass",message:`Typechecked ${String(y.length)} generated program(s)`})}catch(o){t.push({code:"typecheck",level:"fail",message:$(o)})}return{ok:!t.some(o=>o.level==="fail"),productDir:r,checks:t}}function w(e){return d(e)&&Reflect.get(e,"severity")==="error"}function $(e){const t=c(e,"result"),r=c(t,"stderr");if(typeof r=="string"&&r.length>0)return r;const s=c(t,"stdout");return typeof s=="string"&&s.length>0?s:e instanceof Error?e.message:String(e)}function a(e,t){if(!Array.isArray(e))throw new Error(`${t} must be an array`);return e}function b(e,t){if(!d(e))throw new Error(`${t} must be an object`);return e}function c(e,t){return d(e)?Reflect.get(e,t):void 0}function d(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}

package/dist/app/file-selection.d.ts

@@ -0,0 +1 @@
+export declare function resolveRequestedFiles(fileNames: unknown, productDir: unknown, invocationCwd?: unknown): string[];

package/dist/app/file-selection.js

@@ -0,0 +1 @@
+import o from"node:path";export function resolveRequestedFiles(e,r,s=process.cwd()){const t=m(e),i=d(r,"product"),a=d(s,"invocation"),n=[],l=new Set;for(const f of t){const c=p(f,i,a);l.has(c)||(l.add(c),n.push(c))}return n}function p(e,r,s){const t=String(e),i=o.isAbsolute(t)?[t]:[o.resolve(s,t),o.resolve(r,t)];for(const a of i){const n=u(o.relative(r,a));if(!n.startsWith("../")&&n!==".."&&!o.isAbsolute(n))return n.replace(/^\.\/+/,"")}return u(t).replace(/^\.\/+/,"")}function u(e){return e.split(o.sep).join("/")}function m(e){if(!Array.isArray(e))throw new TypeError("Requested test files must be an array");return e}function d(e,r){if(typeof e!="string")throw new TypeError(`Testkit ${r} directory must be a string`);return e}

package/dist/app/inspect/artifacts.d.ts

@@ -0,0 +1,29 @@
+export declare function inspectArtifacts(options: Readonly<{
+    dir?: string;
+    mode: "runs" | "verify" | "artifacts";
+    file: string | null;
+    runId: string | null;
+    service: string | null;
+    kind?: string;
+}>): {
+    mode: "runs";
+    runs: import("../../evidence/contracts.js").RunBundleSummary[];
+    runId?: undefined;
+    verification?: undefined;
+    entries?: undefined;
+} | {
+    mode: "verify";
+    runId: string | null;
+    verification: import("../../evidence/contracts.js").RunBundleVerification;
+    runs?: undefined;
+    entries?: undefined;
+} | {
+    mode: "artifacts";
+    runId: string | null;
+    entries: import("../../evidence/reading.js").CollectedArtifactEntry[];
+    runs?: undefined;
+    verification?: undefined;
+};
+export type ArtifactInspectionEntry = Extract<ReturnType<typeof inspectArtifacts>, {
+    mode: "artifacts";
+}>["entries"][number];

package/dist/app/inspect/artifacts.js

@@ -0,0 +1 @@
+import c from"node:path";import{collectArtifactEntries as d,listRunBundles as u,loadRunArtifact as l,verifyRunBundle as a}from"../../evidence/index.js";export function inspectArtifacts(r){const e=c.resolve(r.dir||process.cwd());if(r.mode==="runs")return{mode:"runs",runs:u(e,{file:r.file})};const t=l(e,r.runId),i=r.runId||t.run.id||null;if(r.mode==="verify")return{mode:"verify",runId:i,verification:a(e,i)};const f=d(e,t,r.file,r.service).filter(n=>!r.kind||n.artifactRef.kind===r.kind);return{mode:"artifacts",runId:i,entries:f}}

package/dist/app/inspect/index.d.ts

@@ -0,0 +1,112 @@
+export { formatTestTypeLabel } from "../../domain/test-types.js";
+import type { RunArtifactSuite } from "../../evidence/index.js";
+import { type EngineId, type RunnerProfileId } from "../../domain/identifiers.js";
+import { type DiscoveryDiagnostic, type DiscoveryResult, type DiscoverySummary } from "../../config/loader/index.js";
+import type { StatusModel } from "../status/model.js";
+export { discoverTests, fileDisplayName, formatDisplayName, testTypeContract } from "../../config/loader/index.js";
+export type { DiscoverTestsOptions, DiscoveryDiagnostic, DiscoveryFile, DiscoveryResult, DiscoveryService, DiscoverySuite, DiscoverySummary, DiscoveryTestContract, DiscoveryTestType, RuntimeIsolationPolicy, } from "../../config/loader/index.js";
+export { listRunBundles, loadRunBundleArtifact, loadRunBundleManifest, verifyRunBundle } from "../../evidence/index.js";
+export type { RunBundleVerification } from "../../evidence/index.js";
+declare const WORKSPACE_SCHEMA_VERSION: 2;
+export type WorkspaceTargetKind = "file" | "project" | "suite";
+export type WorkspaceTargetSource = "discovery" | "latest" | "live";
+export type WorkspaceRunSource = "latest" | "live";
+export interface WorkspaceTargetRef {
+    detail: string;
+    engineId?: null | EngineId;
+    filePath?: string;
+    id: string;
+    kind: WorkspaceTargetKind;
+    label: string;
+    profileId?: null | RunnerProfileId;
+    runnable: boolean;
+    service?: null | string;
+    source: WorkspaceTargetSource;
+    status?: null | string;
+    suiteName?: null | string;
+    testType?: null | RunArtifactSuite["testType"];
+}
+export interface WorkspaceRunSummary {
+    durationMs: null | number;
+    files: {
+        failed: number;
+        notRun: number;
+        passed: number;
+        skipped: number;
+        total: number;
+    };
+    generatedAt: null | string;
+    id: null | string;
+    services: {
+        failed: number;
+        passed: number;
+        skipped: number;
+        total: number;
+    };
+    source: WorkspaceRunSource;
+    startedAt: null | string;
+    status: string;
+    suites: {
+        completed: number;
+        failed: number;
+        passed: number;
+        skipped: number;
+        total: number;
+    };
+    types: string[];
+}
+export interface WorkspaceRuntimeGraphStatus {
+    currentRuntimeDirCount: number;
+    desired: StatusModel["runtimeGraphs"][number]["desired"];
+    exists: boolean;
+    name: string;
+    orphan: boolean;
+    runtimeDirCount: number;
+    staleRuntimeDirCount: number;
+}
+export interface WorkspaceServiceStatus {
+    caches: StatusModel["caches"];
+    hasState: boolean;
+    name: string;
+    product: StatusModel["product"];
+    runtimeGraphs: WorkspaceRuntimeGraphStatus[];
+    runs: {
+        active: number;
+        stale: number;
+        total: number;
+    };
+    warnings: string[];
+}
+export interface WorkspaceStatus {
+    ok: boolean;
+    results: WorkspaceServiceStatus[];
+}
+export interface WorkspaceInspection {
+    activity: {
+        activeRuns: number;
+        staleRuns: number;
+    };
+    discovery: {
+        configFile: null | string;
+        diagnostics: DiscoveryDiagnostic[];
+        summary: DiscoverySummary;
+    } | null;
+    generatedAt: string;
+    product: DiscoveryResult["product"];
+    runs: {
+        latest: WorkspaceRunSummary | null;
+        live: WorkspaceRunSummary | null;
+    };
+    schemaVersion: typeof WORKSPACE_SCHEMA_VERSION;
+    source: "testkit-workspace";
+    status: WorkspaceStatus;
+    targets: WorkspaceTargetRef[];
+    warnings: string[];
+}
+export interface InspectWorkspaceOptions {
+    dir?: string;
+    service?: null | string;
+    status?: boolean;
+    targetLimit?: number;
+}
+export declare function inspectWorkspace(options?: Readonly<InspectWorkspaceOptions>): Promise<WorkspaceInspection>;

package/dist/app/inspect/index.js

@@ -0,0 +1 @@
+export{formatTestTypeLabel}from"../../domain/test-types.js";import{readRunDocument as h}from"../../evidence/read-run.js";import c from"fs";import i from"path";import{errorMessage as u}from"../../kernel/error-serialization.js";import{isPublicTestType as I}from"../../domain/identifiers.js";import{discoverTests as w,formatDisplayName as k}from"../../config/loader/index.js";import{collectServiceStatus as A}from"../status/index.js";export{discoverTests,fileDisplayName,formatDisplayName,testTypeContract}from"../../config/loader/index.js";export{listRunBundles,loadRunBundleArtifact,loadRunBundleManifest,verifyRunBundle}from"../../evidence/index.js";const b=2,S=24,N=String;export async function inspectWorkspace(e={}){const t=E(e.targetLimit,S),r=new Date().toISOString(),s=await $(e),a=s.data?.product.directory||i.resolve(process.cwd(),e.dir||"."),[n,o,l]=await Promise.all([e.status===!1?M():D(e),d(a,"latest"),d(a,"live")]),y=p(o.data,"latest"),g=p(l.data,"live"),T=x({discovery:s.data,latestRunArtifact:o.data,liveRunArtifact:l.data,limit:t}),R=[...s.warnings,...n.warnings,...o.warnings,...l.warnings];return{schemaVersion:b,source:"testkit-workspace",generatedAt:r,product:s.data?.product||{directory:a,name:i.basename(a)},discovery:s.data?{configFile:s.data.configFile||null,diagnostics:s.data.diagnostics,summary:s.data.summary}:null,status:n.data,runs:{latest:y,live:g},targets:T,activity:B(n.data),warnings:R}}async function $(e){try{const t=await w({diagnostics:"report",dir:e.dir,runnableOnly:!1,service:e.service||null}),r=t.diagnostics.filter(s=>s.severity==="error").map(s=>`Discovery diagnostic: ${s.message}`);return{data:t,warnings:r}}catch(t){return{data:null,warnings:[`Discovery unavailable: ${u(t)}`]}}}async function D(e){try{const t=await A({dir:e.dir,service:e.service||null});return{data:j(t),warnings:[]}}catch(t){return{data:{ok:!1,results:[]},warnings:[`Status unavailable: ${u(t)}`]}}}function M(){return Promise.resolve({data:{ok:!0,results:[]},warnings:[]})}function d(e,t){const r=t==="live"?"live.json":"latest.json",s=i.join(e,".testkit","results",r);if(!c.existsSync(s))return Promise.resolve({data:null,warnings:[]});try{const a=h(JSON.parse(c.readFileSync(s,"utf8")),s);return Promise.resolve({data:a,warnings:[]})}catch(a){return Promise.resolve({data:null,warnings:[`${t} run artifact unavailable: ${u(a)}`]})}}function j(e){return{ok:!0,results:e.map(t=>({caches:t.caches,hasState:t.hasState,name:t.name,product:t.product,runtimeGraphs:t.runtimeGraphs.map(r=>({currentRuntimeDirCount:r.currentRuntimeDirs.length,desired:r.desired,exists:r.exists,name:r.name,orphan:r.orphan,runtimeDirCount:r.runtimeDirCount,staleRuntimeDirCount:r.staleRuntimeDirs.length})),runs:{active:t.runs.active,stale:t.runs.stale,total:t.runs.total},warnings:t.warnings}))}}function p(e,t){if(e===null)return null;const{run:r,summary:s}=e;return{durationMs:r.durationMs??null,generatedAt:e.generatedAt??null,id:r.id,startedAt:r.startedAt,status:r.status,types:r.types??[],source:t,files:{failed:s?.files.failed??0,notRun:s?.files.notRun??0,passed:s?.files.passed??0,skipped:s?.files.skipped??0,total:s?.files.total??0},services:{failed:s?.services.failed??0,passed:s?.services.passed??0,skipped:s?.services.skipped??0,total:s?.services.total??0},suites:{completed:s?.suites.completed??0,failed:s?.suites.failed??0,passed:s?.suites.passed??0,skipped:s?.suites.skipped??0,total:s?.suites.total??0}}}function x({discovery:e,latestRunArtifact:t,liveRunArtifact:r,limit:s}){const a=[F(e),...m(r,"live"),...m(t,"latest"),...P(e).slice(0,Math.ceil(s/2)),...C(e).slice(0,s)].filter(n=>n!==null);return L(a).slice(0,s)}function F(e){return e?{detail:e.product.directory,id:"project:all",kind:"project",label:`All tests in ${e.product.name}`,runnable:!0,source:"discovery"}:null}function P(e){return(e?.suites||[]).map(t=>({detail:[t.service,t.testType,t.engineId,t.profileId].filter(Boolean).join(" - "),id:`suite:${t.service}:${t.testType}:${t.engineId}:${t.profileId}:${t.name}`,engineId:t.engineId,kind:"suite",label:t.displayName||t.name,profileId:t.profileId,runnable:t.activeFileCount>0,service:t.service,source:"discovery",suiteName:t.name,testType:t.testType}))}function C(e){return(e?.files||[]).filter(t=>!t.skipped).map(t=>f(t,"discovery"))}function m(e,t){const r=[];for(const s of e?.services??[])for(const a of s.suites)for(const n of a.files??[])n.status!=="failed"&&!n.error||r.push(f({displayName:v(n.path),engineId:a.engineId,path:n.path,profileId:a.profileId,service:s.name,suiteName:a.name,testType:a.testType},t,"failed"));return r}function f(e,t,r=null){return{detail:[e.service,e.testType,e.engineId,e.profileId,e.suiteName].filter(Boolean).join(" - "),filePath:e.path,engineId:e.engineId,id:`file:${e.service||""}:${e.testType}:${e.engineId}:${e.profileId}:${e.path}`,kind:"file",label:e.displayName||v(e.path),profileId:e.profileId,runnable:I(e.testType),service:e.service||null,source:t,status:r||null,suiteName:e.suiteName||null,testType:e.testType}}function B(e){return{activeRuns:e.results.reduce((t,r)=>t+r.runs.active,0),staleRuns:e.results.reduce((t,r)=>t+r.runs.stale,0)}}function L(e){const t=new Set,r=[];for(const s of e)t.has(s.id)||(t.add(s.id),r.push(s));return r}function E(e,t){const r=Number(e);return Number.isFinite(r)?Math.max(1,Math.min(100,Math.round(r))):t}function v(e){return k(i.basename(N(e||"test")).replace(/\.testkit\.[cm]?[jt]sx?$/,""))}

package/dist/app/lint/index.d.ts

@@ -0,0 +1,28 @@
+interface LintOperationFlags {
+    dir?: string;
+}
+export declare function executeLintOperation(flags?: LintOperationFlags): Promise<LintResult>;
+import { type LintOptionsInput, type NormalizedLintOptions } from "./options.js";
+import { type LintFinding } from "./shared.js";
+export interface RunLintOptions extends LintOptionsInput {
+    dir?: string;
+}
+export interface RunLintForConfigOptions {
+    dir?: string;
+}
+export type LintViolation = LintFinding;
+export interface LintSummary {
+    files: number;
+    testkitFiles: number;
+    violations: number;
+}
+export interface LintResult {
+    ok: boolean;
+    productDir: string;
+    summary: LintSummary;
+    violations: LintViolation[];
+}
+export declare function runLint(options?: RunLintOptions): Promise<LintResult>;
+export declare function runLintForConfig(config: unknown, options?: RunLintForConfigOptions): Promise<LintResult>;
+export declare function normalizeLintConfig(config?: unknown): NormalizedLintOptions;
+export {};

package/dist/app/lint/index.js

@@ -0,0 +1,2 @@
+import{loadTestkitConfig as f,resolveProductDir as u}from"../../config/loader/index.js";export async function executeLintOperation(t={}){const n=u(process.cwd(),t.dir),i=await f(n);return runLintForConfig(m(i),{dir:n})}function m(t){if(!(typeof t!="object"||t===null||Array.isArray(t)))return Reflect.get(t,"config")}import c from"node:fs";import r from"node:path";import{normalizeLintOptions as p,normalizeLintConfig as l}from"./options.js";import{collectCurrentFiles as d,collectTrackedFiles as g,isTestkitSuitePath as y}from"./shared.js";import{lintProject as w}from"./native.js";export async function runLint(t={}){const{dir:n,...i}=t,o=r.resolve(process.cwd(),n||".");return a(o,p(i))}export async function runLintForConfig(t,n={}){const i=r.resolve(process.cwd(),n.dir||".");return a(i,l(t))}async function a(t,n){const i=await g(t),o=await d(t),e=await w({productDir:t,files:o,options:n,trackedFiles:i}),s={ok:e.length===0,productDir:t,summary:{files:o.length,testkitFiles:o.filter(y).length,violations:e.length},violations:e};return k(t,s),s}export function normalizeLintConfig(t={}){return l(t)}function k(t,n){try{const i=r.join(t,".testkit","lint");c.mkdirSync(i,{recursive:!0}),c.writeFileSync(r.join(i,"latest.json"),`${JSON.stringify(n,null,2)}
+`,"utf8")}catch{}}

package/dist/app/lint/native.d.ts

@@ -0,0 +1,10 @@
+import { type NormalizedLintOptions } from "./options.js";
+import { type LintFinding } from "./shared.js";
+interface LintProjectInput {
+    productDir: string;
+    files: readonly string[];
+    trackedFiles: readonly string[] | null;
+    options: NormalizedLintOptions;
+}
+export declare function lintProject({ productDir, files, trackedFiles, options, }: LintProjectInput): Promise<LintFinding[]>;
+export {};

package/dist/app/lint/native.js

@@ -0,0 +1 @@
+import y from"node:path";import{ESLint as j}from"eslint";import*as S from"@typescript-eslint/parser";import{LINT_RULE_NAMES as O}from"./options.js";import{compareFindings as _,findingKey as $,isTypeScriptLikePath as B,matchesAnyPathPattern as k,normalizeFinding as c,normalizePath as E,SOURCE_IGNORES as M}from"./shared.js";import{createSyntaxPolicy as F}from"./rules/syntax.js";import{createDataPolicy as U}from"./rules/data.js";import{createUnitPolicy as z}from"./rules/unit.js";import{createEngineImportPolicy as A}from"./rules/engine-imports.js";export async function lintProject({productDir:i,files:n,trackedFiles:o,options:s}){if(j.version!=="10.7.0"||S.version!=="8.65.0")throw new Error("Testkit lint requires its managed eslint@10.7.0 and @typescript-eslint/parser@8.65.0 installation");const h=new Map,I=[],f=O.filter(e=>s.rules[e].enabled),x=Object.fromEntries(f.filter(e=>e!=="testkitBoundary").map(e=>{const t=s.rules[e],r={meta:{type:"problem",schema:[],messages:{violation:"{{message}}"}},defaultOptions:[],create(l){const P=E(y.relative(i,l.filename)),u={context:l,file:P,report:(a,C,L,g)=>{const N=c({file:P,ruleName:e,ruleId:t.ruleId,kind:C,target:L,message:g,line:a.loc.start.line,snippet:l.sourceCode.getText(a).split(/\r?\n/u)[0]});h.set(T(l.filename,a.loc.start.line,a.loc.start.column+1,g),N),l.report({node:a,messageId:"violation",data:{message:g}})},options:s,literals:I};return e==="engineImports"?A(u):e==="dataSuiteContract"?U(u):e==="unitTestBoundaries"?z(u):F(e,u,n)}};return[t.ruleId,r]})),b=new j({cwd:i,overrideConfigFile:!0,allowInlineConfig:!1,errorOnUnmatchedPattern:!1,globInputPaths:!1,warnIgnored:!1,overrideConfig:[{ignores:M},{files:["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"],languageOptions:{parser:S,ecmaVersion:"latest",sourceType:"module"},plugins:{testkit:{rules:x}}},...f.filter(e=>e!=="testkitBoundary").map(e=>{const t=s.rules[e];return{files:t.include.length?t.include:["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"],ignores:t.exclude,rules:{[`testkit/${t.ruleId}`]:"error"}}})]}),w=[],v=n.filter(B);v.length&&w.push(...await b.lintFiles(v.map(e=>y.join(i,e))));const d=w.flatMap(e=>e.messages.map(t=>{if(t.ruleId===null)return c({file:E(y.relative(i,e.filePath)),line:t.line,ruleName:"syntax",ruleId:"syntax",kind:"parse-error",target:t.message,message:t.message});const r=h.get(T(e.filePath,t.line,t.column,t.message));if(!r)throw new Error(`Missing Testkit finding for ${t.ruleId}: ${t.message}`);return r}));if(f.includes("testkitBoundary")){const e=s.rules.testkitBoundary,t=o&&new Set(o);for(const r of n)e.trackedOnly&&t&&!t.has(r)||!R(r,e)||!r.split("/").some(l=>l.toLowerCase().includes("testkit"))||k(r,e.allowed??[])||d.push(c({file:r,ruleName:"testkitBoundary",ruleId:e.ruleId,kind:"testkit-path",target:r,message:"Tracked Testkit plumbing must live in testkit.config.* or __testkit__/ suites, or move into @gfdelarue/testkit"}))}const m=new Map;for(const e of I){const t=`${e.field}:${e.value}`,r=m.get(t)??[];r.push(e),m.set(t,r)}for(const[e,t]of m)if(!(new Set(t.map(r=>r.file)).size<2))for(const r of t)d.push(c({...r,ruleName:"dalParallelSafety",ruleId:"dal-parallel-safety",kind:"duplicate-literal",target:e,message:`Duplicate ${r.field} literal "${r.value}" appears across DAL specs; use fixture-derived namespaced values`}));const p=new Map;for(const e of d.sort(_)){const t=$(e);p.has(t)||p.set(t,e)}return[...p.values()]}function T(i,n,o,s){return[i,n,o,s].join("\0")}function R(i,n){return(!n.include.length||k(i,n.include))&&!k(i,n.exclude)}

package/dist/app/lint/options.d.ts

@@ -0,0 +1,67 @@
+export interface LintRulePolicy {
+    allowed?: string[];
+    enabled: boolean;
+    exclude: string[];
+    include: string[];
+    ruleId: string;
+    ruleName: LintRuleName;
+    trackedOnly?: boolean;
+}
+export interface LintRuleOptionsInput {
+    allowed?: readonly string[];
+    enabled?: boolean;
+    exclude?: readonly string[];
+    include?: readonly string[];
+    trackedOnly?: boolean;
+}
+export type LintRuleInput = boolean | LintRuleOptionsInput;
+export interface LintOptionsInput {
+    rules?: Partial<Record<LintRuleName, LintRuleInput>>;
+    ui?: {
+        maxLines?: number;
+        maxTests?: number;
+    };
+}
+export interface NormalizedLintOptions {
+    rules: LintRulePolicies;
+    ui: {
+        maxLines: number;
+        maxTests: number;
+    };
+}
+export declare const LINT_RULE_NAMES: readonly ["engineImports", "uiSpecShape", "dalParallelSafety", "dataSuiteContract", "configImports", "testkitBoundary", "unitTestBoundaries"];
+export type LintRuleName = (typeof LINT_RULE_NAMES)[number];
+export type LintRulePolicies = Record<LintRuleName, LintRulePolicy>;
+export declare function isLintRuleName(value: string): value is LintRuleName;
+export declare const RULES: {
+    readonly engineImports: {
+        readonly ruleId: "engine-imports";
+        readonly defaultEnabled: true;
+    };
+    readonly uiSpecShape: {
+        readonly ruleId: "ui-spec-shape";
+        readonly defaultEnabled: true;
+    };
+    readonly dalParallelSafety: {
+        readonly ruleId: "dal-parallel-safety";
+        readonly defaultEnabled: true;
+    };
+    readonly dataSuiteContract: {
+        readonly ruleId: "data-suite-contract";
+        readonly defaultEnabled: true;
+    };
+    readonly configImports: {
+        readonly ruleId: "config-imports";
+        readonly defaultEnabled: true;
+    };
+    readonly testkitBoundary: {
+        readonly ruleId: "testkit-boundary";
+        readonly defaultEnabled: false;
+    };
+    readonly unitTestBoundaries: {
+        readonly ruleId: "unit-test-boundaries";
+        readonly defaultEnabled: false;
+    };
+};
+export declare function normalizeLintConfig(config?: unknown): NormalizedLintOptions;
+export declare function normalizeLintOptions(options?: LintOptionsInput): NormalizedLintOptions;

package/dist/app/lint/options.js

@@ -0,0 +1 @@
+import{DEFAULT_TESTKIT_BOUNDARY_ALLOWED as a,isObjectRecord as l,normalizePath as y}from"./shared.js";export const LINT_RULE_NAMES=["engineImports","uiSpecShape","dalParallelSafety","dataSuiteContract","configImports","testkitBoundary","unitTestBoundaries"];const b=new Set(LINT_RULE_NAMES),m=new Set(["rules","ui"]),p=new Set(["enabled","exclude","include"]),S=new Set([...p,"allowed","trackedOnly"]),I=new Set(["maxLines","maxTests"]),u="lint levels were removed; set a rule to true or false, or use { enabled: boolean }";export function isLintRuleName(e){return b.has(e)}export const RULES={engineImports:{ruleId:"engine-imports",defaultEnabled:!0},uiSpecShape:{ruleId:"ui-spec-shape",defaultEnabled:!0},dalParallelSafety:{ruleId:"dal-parallel-safety",defaultEnabled:!0},dataSuiteContract:{ruleId:"data-suite-contract",defaultEnabled:!0},configImports:{ruleId:"config-imports",defaultEnabled:!0},testkitBoundary:{ruleId:"testkit-boundary",defaultEnabled:!1},unitTestBoundaries:{ruleId:"unit-test-boundaries",defaultEnabled:!1}};const O=220,T=8;export function normalizeLintConfig(e={}){const n=l(e)?e.lint??{}:{};return normalizeLintOptions(n)}export function normalizeLintOptions(e={}){if(!l(e))throw new Error("lint config must be an object");if(Object.prototype.hasOwnProperty.call(e,"level"))throw new Error(`lint.level was removed; ${u}`);f(e,m,"lint");const n=e.rules??{};if(!l(n))throw new Error("lint.rules must be an object");for(const i of Object.keys(n)){if(i==="missingImports")throw new Error("lint.rules.missingImports was removed; use testkit typecheck for TypeScript import diagnostics");if(!Object.prototype.hasOwnProperty.call(RULES,i))throw new Error(`Unknown lint rule "${i}"`)}const t=i=>{const s=RULES[i];return _({ruleName:i,ruleId:s.ruleId,value:n[i],defaultEnabled:s.defaultEnabled})},r={engineImports:t("engineImports"),configImports:t("configImports"),dalParallelSafety:t("dalParallelSafety"),dataSuiteContract:t("dataSuiteContract"),testkitBoundary:t("testkitBoundary"),uiSpecShape:t("uiSpecShape"),unitTestBoundaries:t("unitTestBoundaries")},o=e.ui===void 0?{}:e.ui;if(!l(o))throw new Error("lint.ui must be an object");return f(o,I,"lint.ui"),{rules:r,ui:{maxLines:w(o.maxLines,O,"lint.ui.maxLines"),maxTests:w(o.maxTests,T,"lint.ui.maxTests")}}}function _({ruleName:e,ruleId:n,value:t,defaultEnabled:r}){if(t===void 0)return d({ruleName:e,ruleId:n,enabled:r});if(typeof t=="boolean")return d({ruleName:e,ruleId:n,enabled:t});if(!l(t))throw new Error(`lint.rules.${e} must be true, false, or a rule config object; ${u}`);if(Object.prototype.hasOwnProperty.call(t,"level"))throw new Error(`lint.rules.${e}.level was removed; ${u}`);return f(t,e==="testkitBoundary"?S:p,`lint.rules.${e}`),d({ruleName:e,ruleId:n,enabled:E(t.enabled,`lint.rules.${e}.enabled`)??!0,include:c(t.include,`lint.rules.${e}.include`),exclude:c(t.exclude,`lint.rules.${e}.exclude`),allowed:e==="testkitBoundary"?h(t.allowed):void 0,trackedOnly:e==="testkitBoundary"?E(t.trackedOnly,`lint.rules.${e}.trackedOnly`):void 0})}function d({ruleName:e,ruleId:n,enabled:t,include:r=[],exclude:o=[],allowed:i,trackedOnly:s}){return{ruleName:e,ruleId:n,enabled:t,include:r,exclude:o,...e==="testkitBoundary"?{allowed:i||a}:{},...e==="testkitBoundary"?{trackedOnly:s!==!1}:{}}}function c(e,n){if(e==null)return[];if(!Array.isArray(e))throw new Error(`${n} must be an array`);return e.map((t,r)=>{const o=typeof t=="string"?t.trim():"";if(!o)throw new Error(`${n}[${String(r)}] must be a non-empty string`);return y(o)})}function h(e){if(e==null)return a;const n=c(e,"lint.rules.testkitBoundary.allowed");return n.length>0?n:a}function w(e,n,t){if(e===void 0)return n;if(typeof e!="number"||!Number.isInteger(e)||e<=0)throw new Error(`${t} must be a positive integer`);return e}function E(e,n){if(e!==void 0){if(typeof e!="boolean")throw new Error(`${n} must be a boolean`);return e}}function f(e,n,t){for(const r of Object.keys(e))if(!n.has(r))throw new Error(`Unknown ${t} option "${r}"`)}

package/dist/app/lint/policy.d.ts

@@ -0,0 +1,21 @@
+import type { TSESLint, TSESTree } from "@typescript-eslint/utils";
+import type { NormalizedLintOptions } from "./options.js";
+export type PolicyContext = TSESLint.RuleContext<"violation", []>;
+export type Report = (node: TSESTree.Node, kind: string, target: string, message: string) => void;
+export interface LiteralFact {
+    field: string;
+    value: string;
+    file: string;
+    line: number;
+    snippet: string;
+}
+export interface PolicyInput {
+    context: PolicyContext;
+    file: string;
+    report: Report;
+    options: NormalizedLintOptions;
+    literals: LiteralFact[];
+}
+export declare function stringValue(node: TSESTree.Node | null | undefined): string | null;
+export declare function memberName(node: TSESTree.MemberExpression): string | null;
+export declare function binding(context: PolicyContext, node: TSESTree.Identifier): TSESLint.Scope.Variable | null;

package/dist/app/lint/policy.js

@@ -0,0 +1 @@
+import{AST_NODE_TYPES as t}from"@typescript-eslint/utils";export function stringValue(e){return e?.type===t.Literal&&typeof e.value=="string"?e.value:e?.type===t.TemplateLiteral&&e.expressions.length===0?e.quasis[0]?.value.cooked??null:null}export function memberName(e){return!e.computed&&e.property.type===t.Identifier?e.property.name:stringValue(e.property)}export function binding(e,p){for(let r=e.sourceCode.getScope(p);r;r=r.upper){const u=r.set.get(p.name);if(u)return u}return null}

package/dist/app/lint/rules/data.d.ts

@@ -0,0 +1,3 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+import { type PolicyInput } from "../policy.js";
+export declare function createDataPolicy({ context, file, report }: PolicyInput): TSESLint.RuleListener;

package/dist/app/lint/rules/data.js

@@ -0,0 +1 @@
+import{AST_NODE_TYPES as r}from"@typescript-eslint/utils";import{binding as p,memberName as w,stringValue as E}from"../policy.js";const T=new Set(["addFinding","actor","budget","bytes","count","duration","event","externalCall","expectMetric","expectSequence","fixture","finding","http","metric","money","ratio","reconcile","record","recordCache","recordHttpRequest","recordLlmUsage","recordRpc","sequence","sequenceBudget","system","transition"]),N=new Set(["actor","bytes","duration","externalCall","http","money","ratio","reconcile","record","recordCache","recordHttpRequest","recordLlmUsage","recordRpc","sequence","system","transition"]),f=new Set(["bench","describe","it","suite","test","BenchmarkRunner","TestRunner","EvaluatedModules"]);export function createDataPolicy({context:o,file:C,report:n}){if(!C.endsWith(".data.testkit.ts"))return{};const d=new Set,h=new Set,v=new Map,g=new Map;let y=!1,b=!1;const u=(e,t,a="vitest-runner-import")=>{n(e,a,t,`Data suites cannot use ${t} for Vitest case registration; declare cases with dataScenario(...)`)},x=e=>{for(const t of o.sourceCode.getAncestors(e).reverse())if(t.type===r.ArrowFunctionExpression||t.type===r.FunctionExpression){const a=g.get(t);if(a)return a}},m=e=>e.startsWith("vitest/")&&e!=="vitest/package.json"||e==="@gfdelarue/testkit/node-vitest/contract",k=e=>{E(e)?.includes("{serviceContextUrl:")&&n(e,"service-namespace-url","serviceContextUrl","Data suites must not use serviceContextUrl placeholders because they run outside the deployed service namespace")};return{ImportDeclaration(e){const t=e.source.value;if(t==="@playwright/test"&&n(e,"browser-runtime-import",t,"Browser/runtime driving belongs in ui or e2e suites, not data suites"),(t.startsWith("@testing-library/")||t==="jsdom"||t==="happy-dom")&&n(e,"dom-runtime-import","dom-runtime","DOM/rendering tests belong in ui suites, not data suites"),e.importKind==="type")return;const a=e.specifiers.filter(s=>s.type!==r.ImportSpecifier||s.importKind!=="type");if(!(e.specifiers.length&&!a.length)){m(t)&&u(e,t),t==="@gfdelarue/testkit/node-vitest/data"&&(y=!0);for(const s of a){const i=o.sourceCode.getDeclaredVariables(e).find(l=>l.name===s.local.name);if(t==="vitest"&&s.type===r.ImportNamespaceSpecifier&&i&&h.add(i),s.type!==r.ImportSpecifier)continue;const c=s.imported.type===r.Identifier?s.imported.name:s.imported.value;t==="vitest"&&f.has(c)&&u(s,c),t==="@gfdelarue/testkit/node-vitest/data"&&c==="dataScenario"&&i&&d.add(i)}}},ExportNamedDeclaration(e){if(!e.source||e.exportKind==="type")return;const t=e.specifiers.filter(a=>a.exportKind!=="type");if(!(e.specifiers.length&&!t.length)&&(m(e.source.value)&&u(e,e.source.value),e.source.value==="vitest"))for(const a of t){const s=a.local.type===r.Identifier?a.local.name:a.local.value;f.has(s)&&u(a,s)}},ExportAllDeclaration(e){e.exportKind!=="type"&&m(e.source.value)&&u(e,e.source.value)},MemberExpression(e){if(e.object.type!==r.Identifier)return;const t=p(o,e.object),a=w(e);t&&h.has(t)&&a&&f.has(a)&&u(e,a,"vitest-runner-call")},CallExpression(e){const t=e.callee.type===r.Identifier?p(o,e.callee):null;if(t&&d.has(t)){b=!0;const i=e.arguments.at(-1);if(!i||i.type!==r.ArrowFunctionExpression&&i.type!==r.FunctionExpression){n(e,"missing-scenario-callback","dataScenario","dataScenario(...) must provide a callback that receives the Testkit data context");return}const c=i.params[0]?.type===r.AssignmentPattern?i.params[0].left:i.params.at(0),l=c?.type===r.Identifier?o.sourceCode.getDeclaredVariables(i).find(D=>D.name===c.name):null;if(!l){n(e,"missing-data-context","dataScenario","dataScenario callbacks must accept the Testkit data context and record data evidence");return}const S={callback:i,context:l,contextName:l.name,methods:new Set,assertion:!1};v.set(e,S),g.set(i,S);return}const a=o.sourceCode.getText(e.callee);e.callee.type===r.MemberExpression&&a.includes(".serviceContextUrl")&&n(e,"service-namespace-url","serviceContextUrl","Data suites run in the managed Node.js runner, not inside a service namespace; use baseUrl/public endpoints or move service-namespace checks to int/e2e");const s=x(e);if(s&&(/^(expect|assert)(?:\(|\.)/u.test(a)&&(s.assertion=!0),e.callee.type===r.MemberExpression&&e.callee.object.type===r.Identifier&&p(o,e.callee.object)===s.context)){const i=w(e.callee);i&&T.has(i)&&s.methods.add(i)}},"CallExpression:exit"(e){const t=v.get(e);if(!t)return;const{callback:a,contextName:s,methods:i,assertion:c}=t;i.size?[...i].some(l=>N.has(l))||(n(a,"weak-data-evidence",s,"Data scenarios must record product data-flow evidence such as http, bytes, sequence, record, transition, system, externalCall, recordCache, recordLlmUsage, or reconcile; ordinary Node/Vitest-style checks belong in *.contract.testkit.ts with @gfdelarue/testkit/node-vitest/contract"),c&&n(a,"vitest-shaped-data-suite",s,"This dataScenario looks like an ordinary assertion test with weak data bookkeeping; move Node-backed contract checks to *.contract.testkit.ts or model the product data flow with structured evidence")):n(a,"missing-data-evidence",s,"Data scenarios must record Testkit-owned data-flow evidence with the data context, such as http, bytes, sequence, record, transition, system, externalCall, recordCache, recordLlmUsage, or reconcile")},ThrowStatement(e){const t=x(e);t&&(t.assertion=!0)},Literal:k,TemplateLiteral:k,"Program:exit"(e){y?d.size?b||n(e,"missing-data-scenario","dataScenario","Data suites must declare at least one dataScenario(...)"):n(e,"missing-data-scenario-import","dataScenario","Data suites must import dataScenario from @gfdelarue/testkit/node-vitest/data"):n(e,"missing-data-import","@gfdelarue/testkit/node-vitest/data","Data suites must import dataScenario from @gfdelarue/testkit/node-vitest/data")}}}

package/dist/app/lint/rules/engine-imports.d.ts

@@ -0,0 +1,3 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+import { type PolicyInput } from "../policy.js";
+export declare function createEngineImportPolicy({ context, file, report }: PolicyInput): TSESLint.RuleListener;

package/dist/app/lint/rules/engine-imports.js

@@ -0,0 +1 @@
+import{AST_NODE_TYPES as l}from"@typescript-eslint/utils";import{isPublicTestType as g}from"../../../domain/identifiers.js";import{BUILT_IN_ENGINE_CATALOG as I,expectedEngineAuthoringModule as h,invalidEngineAuthoringImport as E,requireMatchingHostImport as x}from"../../../engines/catalog.js";import{binding as y,stringValue as c}from"../policy.js";export function createEngineImportPolicy({context:u,file:i,report:m}){const n=/\.([^.]+)\.testkit\.ts$/u.exec(i)?.[1];if(!g(n))return{};const p=I.profilesForTestType(n),o=p[0];if(p.length!==1)return{};const a={engineId:o.engineId,profileId:o.id},f=h(o.id),r=(t,e)=>{if(e!==null)try{if(x(i,a,e),e!==f&&(e.startsWith("@gfdelarue/testkit/")||e.startsWith("@gfdelarue/testkit-engine-")))throw E(i,a,e)}catch(s){if(!(s instanceof Error))throw s;m(t,"engine-import",e,s.message)}};return{ImportDeclaration(t){t.importKind!=="type"&&(t.specifiers.length===0||t.specifiers.some(e=>e.type!==l.ImportSpecifier||e.importKind!=="type"))&&r(t,t.source.value)},ExportNamedDeclaration(t){t.source&&t.exportKind!=="type"&&t.specifiers.some(e=>e.exportKind!=="type")&&r(t,t.source.value)},ExportAllDeclaration(t){t.exportKind!=="type"&&r(t,t.source.value)},ImportExpression(t){r(t,c(t.source))},CallExpression(t){t.callee.type===l.Identifier&&t.callee.name==="require"&&!y(u,t.callee)?.defs.length&&r(t,c(t.arguments[0]))}}}

package/dist/app/lint/rules/syntax.d.ts

@@ -0,0 +1,4 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+import type { LintRuleName } from "../options.js";
+import { type PolicyInput } from "../policy.js";
+export declare function createSyntaxPolicy(name: LintRuleName, { file, context, report, options, literals }: PolicyInput, files: readonly string[]): TSESLint.RuleListener;

package/dist/app/lint/rules/syntax.js

@@ -0,0 +1 @@
+import{AST_NODE_TYPES as a}from"@typescript-eslint/utils";import{memberName as O,stringValue as u}from"../policy.js";export function createSyntaxPolicy(n,{file:s,context:c,report:l,options:r,literals:m},N){if(n==="uiSpecShape"&&s.endsWith(".ui.testkit.ts")){let t=0;return{CallExpression(e){e.callee.type===a.Identifier&&e.callee.name==="test"&&u(e.arguments[0])!==null&&(t+=1)},"Program:exit"(e){const i=c.sourceCode.text.split(/\r?\n/u).length;(i>r.ui.maxLines||t>r.ui.maxTests)&&l(e,"shape-limit",`${String(i)}:${String(t)}`,`UI spec exceeds shape limit (${String(i)}/${String(r.ui.maxLines)} lines, ${String(t)}/${String(r.ui.maxTests)} tests)`)}}}if(n==="configImports"&&s===N.find(t=>/^testkit\.config\.[cm]?[jt]s$/u.test(t)))return{ImportDeclaration(t){const e=t.source.value;(e.startsWith(".")||e.startsWith("/"))&&e.includes("__testkit__")&&l(t,"config-helper-import",e,"testkit.config.ts must not import repo-local __testkit__ helper modules")}};if(n!=="dalParallelSafety")return{};const o=s.endsWith(".dal.testkit.ts"),p=s.split("/").includes("__testkit__")&&s.split("/").includes("helpers")&&s.endsWith(".ts");return{CallExpression(t){if(!o)return;const e=t.callee;(e.type===a.Identifier&&e.name==="truncate"||e.type===a.MemberExpression&&O(e)==="truncate")&&l(t,"truncate","truncate","DAL specs must not truncate shared tables; seed namespaced rows and scope queries instead")},Property(t){if(!o)return;const e=!t.computed&&t.key.type===a.Identifier?t.key.name:u(t.key),i=u(t.value);e&&["slug","email","authProviderId"].includes(e)&&i&&m.push({field:e,value:i,file:s,line:t.loc.start.line,snippet:c.sourceCode.getText(t).split(/\r?\n/u)[0]})},Literal(t){p&&typeof t.value=="string"&&/\bON\s+CONFLICT(?:\s*\([^)]*\))?\s+DO\s+NOTHING\b/iu.test(t.value)&&l(t,"silent-conflict","ON CONFLICT DO NOTHING","Testkit helper seed code must not use ON CONFLICT DO NOTHING; collisions should fail loudly")},TemplateLiteral(t){p&&/\bON\s+CONFLICT(?:\s*\([^)]*\))?\s+DO\s+NOTHING\b/iu.test(t.quasis.map(e=>e.value.cooked??"").join("\0"))&&l(t,"silent-conflict","ON CONFLICT DO NOTHING","Testkit helper seed code must not use ON CONFLICT DO NOTHING; collisions should fail loudly")}}}

package/dist/app/lint/rules/unit.d.ts

@@ -0,0 +1,3 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+import { type PolicyInput } from "../policy.js";
+export declare function createUnitPolicy({ file, report }: PolicyInput): TSESLint.RuleListener;

package/dist/app/lint/rules/unit.js

@@ -0,0 +1 @@
+import{AST_NODE_TYPES as o}from"@typescript-eslint/utils";import{memberName as a,stringValue as m}from"../policy.js";const u=new Set(["vi.mock","jest.mock","mock.method"]),p=new Set(["vi.fn","vi.spyOn","vi.stubGlobal","vi.useFakeTimers","jest.fn","jest.spyOn","jest.useFakeTimers"]),b=new Set(["sinon","nock","msw","jest-mock"]),f=new Set(["fetch","http.createServer","net.createServer"]),l=new Set(["fs","node:fs","child_process","node:child_process","execa"]);export function createUnitPolicy({file:r,report:s}){if(!/\.(test|spec)\.[cm]?[jt]sx?$/u.test(r)||r.split("/").includes("__testkit__"))return{};const i=(e,t)=>{if(!t)return;const c=t.split("/"),n=t.startsWith("@")?c.slice(0,2).join("/"):c[0];b.has(n)&&s(e,"test-double-library",n,"Unit tests must not use test-double libraries"),(l.has(t)||l.has(n))&&s(e,"io-boundary-import",t,"Unit tests must not import process, network, filesystem, or runtime boundary modules")};return{ImportDeclaration(e){i(e,e.source.value)},ImportExpression(e){i(e,m(e.source))},CallExpression(e){const t=h(e.callee);u.has(t)&&s(e,"module-replacement",t,"Unit tests must not replace modules; move boundary behavior to a Testkit suite"),p.has(t)&&s(e,"function-replacement",t,"Unit tests must not replace collaborators; extract pure logic or move behavior to a Testkit suite"),f.has(t)&&s(e,"io-boundary-call",t,"Unit tests must not cross process, network, filesystem, or runtime boundaries"),t==="require"&&e.arguments.length===1&&i(e,m(e.arguments[0]))},MemberExpression(e){e.object.type===o.Identifier&&e.object.name==="process"&&a(e)==="env"&&s(e,"io-boundary-global","process.env","Unit tests must not read process-global environment state")}}}function h(r){if(r.type===o.Identifier)return r.name;if(r.type!==o.MemberExpression)return"";let s=r.object;for(;s.type===o.MemberExpression;)s=s.object;const i=a(r);return s.type===o.Identifier&&i?`${s.name}.${i}`:""}

package/dist/app/lint/shared.d.ts

@@ -0,0 +1,36 @@
+export interface LintFindingInput {
+    file: string;
+    kind?: string;
+    line?: number;
+    message: string;
+    ruleId: string;
+    ruleName: string;
+    snippet?: string | null;
+    target?: string;
+}
+export interface LintFinding {
+    file: string;
+    kind: string;
+    line: number;
+    message: string;
+    ruleId: string;
+    ruleName: string;
+    snippet?: string;
+    target: string;
+}
+export declare const DEFAULT_EXCLUDED_DIRS: string[];
+export declare const SOURCE_PATTERNS: string[];
+export declare const SOURCE_IGNORES: string[];
+export declare const DEFAULT_TESTKIT_BOUNDARY_ALLOWED: string[];
+export declare function collectCurrentFiles(productDir: string): Promise<string[]>;
+export declare function collectTrackedFiles(productDir: string): Promise<string[] | null>;
+export declare function normalizePath(value: string): string;
+export declare function isObjectRecord(value: unknown): value is Record<string, unknown>;
+export declare function isSourceLikePath(file: string): boolean;
+export declare function isTypeScriptLikePath(file: string): boolean;
+export declare function isTestkitSuitePath(file: string): boolean;
+export declare function isExcludedRelativePath(file: string): boolean;
+export declare function matchesAnyPathPattern(file: string, patterns: readonly string[]): boolean;
+export declare function compareFindings(left: LintFinding, right: LintFinding): number;
+export declare function normalizeFinding(finding: LintFindingInput): LintFinding;
+export declare function findingKey(finding: Readonly<LintFinding>): string;

package/dist/app/lint/shared.js

@@ -0,0 +1 @@
+import n from"node:fs";import s from"node:path";import{minimatch as i}from"minimatch";import{glob as c}from"tinyglobby";import{TEST_TYPE_ORDER as p}from"../../domain/test-types.js";import{runManagedGitCommand as l}from"../../repo/managed-git.js";export const DEFAULT_EXCLUDED_DIRS=[".git",".next",".next-testkit",".testkit","coverage","dist","node_modules","playwright-report"],SOURCE_PATTERNS=["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts,json}"],SOURCE_IGNORES=DEFAULT_EXCLUDED_DIRS.map(t=>`**/${t}/**`),DEFAULT_TESTKIT_BOUNDARY_ALLOWED=["testkit.config.ts","testkit.config.mts","testkit.config.mjs","testkit.config.js","**/__testkit__/**"];export async function collectCurrentFiles(t){const e=await l(t,["ls-files","--cached","--others","--exclude-standard","-z"]),o=e.exitCode===0?e.stdout.split("\0").filter(r=>r&&n.existsSync(s.join(t,r))):await c(SOURCE_PATTERNS,{cwd:t,ignore:SOURCE_IGNORES,dot:!0,followSymbolicLinks:!1});return[...new Set(o.map(normalizePath))].filter(r=>isSourceLikePath(r)&&!isExcludedRelativePath(r)).sort((r,a)=>r.localeCompare(a))}export async function collectTrackedFiles(t){const e=await l(t,["ls-files","-z"]);return e.exitCode!==0?null:e.stdout.split("\0").map(o=>normalizePath(o)).filter(Boolean).filter(o=>n.existsSync(s.join(t,o))).sort((o,r)=>o.localeCompare(r))}export function normalizePath(t){return t.split(s.sep).join("/")}export function isObjectRecord(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}export function isSourceLikePath(t){return/\.(?:[cm]?[jt]sx?|json)$/u.test(t)}export function isTypeScriptLikePath(t){return/\.[cm]?[jt]sx?$/u.test(t)}export function isTestkitSuitePath(t){return p.some(e=>t.endsWith(`.${e}.testkit.ts`))}export function isExcludedRelativePath(t){return SOURCE_IGNORES.some(e=>i(t,e,{dot:!0}))}export function matchesAnyPathPattern(t,e){return e.some(o=>i(t,o,{dot:!0}))}export function compareFindings(t,e){return t.file.localeCompare(e.file)||t.line-e.line||t.ruleId.localeCompare(e.ruleId)||t.kind.localeCompare(e.kind)||t.target.localeCompare(e.target)}export function normalizeFinding(t){return{ruleName:t.ruleName,ruleId:t.ruleId,kind:t.kind||"violation",target:t.target||"",file:normalizePath(t.file),line:t.line||1,message:t.message,...t.snippet?{snippet:t.snippet}:{}}}export function findingKey(t){return[t.file,String(t.line),t.ruleId,t.kind,t.target].join("\0")}

package/dist/app/package-inspection.d.ts

@@ -0,0 +1,20 @@
+export interface PackageVersionInspectionOptions {
+    binUrl?: string | URL;
+    currentPackageRoot?: string;
+    cwd?: string;
+    dir?: string | null;
+}
+export interface PackageVersionMismatch {
+    currentPackageRoot: string;
+    currentVersion: string;
+    declaredSpec: string | null;
+    productDir: string;
+    productPackageRoot: string | null;
+    productVersion: string | null;
+}
+export declare function testkitIdentity(): {
+    description: string;
+    name: string;
+    version: string;
+};
+export declare function inspectPackageVersionDrift(options?: Readonly<PackageVersionInspectionOptions>): PackageVersionMismatch | null;

package/dist/app/package-inspection.js

@@ -0,0 +1 @@
+import p from"node:fs";import r from"node:path";import{fileURLToPath as P}from"node:url";import{satisfiesSemver as v}from"../toolchains/semver.js";import{readPackageMetadata as D}from"../process/host/metadata.js";const S=["dependencies","devDependencies","optionalDependencies","peerDependencies"];export function testkitIdentity(){return{description:"Test orchestration platform for product acceptance and QA workflows",name:"@gfdelarue/testkit",version:D().version}}export function inspectPackageVersionDrift(e={}){const n=e.currentPackageRoot||j(e.binUrl||import.meta.url),t=a(r.join(n,"package.json"));if(!t?.version)throw new Error(`Unable to read the current Testkit version from ${n}`);const c=e.cwd||process.cwd(),s=e.dir?r.resolve(c,e.dir):c;if(f(s,n))return null;const g=a(r.join(s,"package.json")),o=R(g),d=r.join(s,"node_modules","@gfdelarue","testkit"),i=a(r.join(d,"package.json"));return!o&&!i||i&&f(d,n)?null:i?.version&&i.version!==t.version?{productDir:s,currentPackageRoot:n,currentVersion:t.version,productPackageRoot:d,productVersion:i.version,declaredSpec:o}:!i&&o&&h(o)&&!v(t.version,l(o))?{productDir:s,currentPackageRoot:n,currentVersion:t.version,productPackageRoot:null,productVersion:null,declaredSpec:o}:null}function j(e){const n=P(e);return y(r.dirname(n))}function y(e){let n=r.resolve(e);for(;;){if(a(r.join(n,"package.json"))?.name==="@gfdelarue/testkit")return n;const c=r.dirname(n);if(c===n)return r.resolve(e);n=c}}function R(e=null){for(const n of S){const t=e?.[n]?.["@gfdelarue/testkit"];if(t?.trim())return t.trim()}return null}function a(e){try{const n=JSON.parse(p.readFileSync(e,"utf8"));return w(n)}catch{return null}}function f(e,n){try{return p.realpathSync(e)===p.realpathSync(n)}catch{return r.resolve(e)===r.resolve(n)}}function h(e){const n=l(e);return/^(?:[<>]=?|[\^~=])?\s*\d/u.test(n)}function l(e){return e.trim().replace(/^workspace:/u,"")}function w(e){return k(e)?{dependencies:u(e.dependencies),devDependencies:u(e.devDependencies),name:m(e.name),optionalDependencies:u(e.optionalDependencies),peerDependencies:u(e.peerDependencies),version:m(e.version)}:null}function u(e){if(!k(e))return;const n=Object.entries(e).filter(t=>typeof t[1]=="string");return Object.fromEntries(n)}function m(e){return typeof e=="string"?e:void 0}function k(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}

package/dist/app/run/endpoint-readiness.d.ts

@@ -0,0 +1,43 @@
+import { type EndpointReadinessAttempt } from "../../process/readiness.js";
+import type { NormalizedFailureDetail } from "./failure-details.js";
+export interface EndpointReadinessOptions {
+    attemptTimeoutMs?: number | string;
+    mode?: string;
+    retryDelayMs?: number | string;
+    timeoutMs?: number | string;
+}
+export interface EndpointReadinessLifecycle {
+    isStopRequested(): boolean;
+}
+export interface EndpointReadinessInput {
+    baseUrl: string;
+    env?: NodeJS.ProcessEnv;
+    lifecycle?: EndpointReadinessLifecycle | null;
+    options?: Readonly<EndpointReadinessOptions>;
+    serviceName?: string | null;
+    signal?: AbortSignal;
+}
+export interface EndpointReadinessFailureDetail extends NormalizedFailureDetail {
+    classification: "infra";
+    endpoint: string;
+    key: "http_endpoint_readiness";
+    kind: "http_endpoint_readiness";
+    message: string;
+    service: string | null;
+    title: "HTTP endpoint readiness failed";
+}
+export interface EndpointReadinessSuccess {
+    attempts: EndpointReadinessAttempt[];
+    ok: true;
+    skipped: boolean;
+}
+export interface EndpointReadinessFailure {
+    attempts: EndpointReadinessAttempt[];
+    failureDetails: EndpointReadinessFailureDetail[];
+    ok: false;
+    reason: string;
+    skipped: false;
+}
+export type EndpointReadinessResult = EndpointReadinessFailure | EndpointReadinessSuccess;
+export declare function shouldRunEndpointReadinessPreflight(baseUrl: string, options?: Readonly<EndpointReadinessOptions>, env?: NodeJS.ProcessEnv): boolean;
+export declare function waitForEndpointReadinessPreflight({ baseUrl, serviceName, lifecycle, options, env, signal, }: Readonly<EndpointReadinessInput>): Promise<EndpointReadinessResult>;

package/dist/app/run/endpoint-readiness.js

@@ -0,0 +1 @@
+import{connectEndpoint as E}from"../../process/readiness.js";const P=new Set(["localhost","127.0.0.1","::1"]);export function shouldRunEndpointReadinessPreflight(t,e={},n=process.env){const r=(e.mode||n.TESTKIT_HTTP_ENDPOINT_PREFLIGHT||"auto").trim().toLowerCase();if(["0","false","off","never","disabled"].includes(r))return!1;if(["1","true","on","always","force"].includes(r))return!0;const o=d(t);return!!(o&&!P.has(l(o.host)))}export async function waitForEndpointReadinessPreflight({baseUrl:t,serviceName:e,lifecycle:n=null,options:r={},env:o=process.env,signal:i}){if(!shouldRunEndpointReadinessPreflight(t,r,o))return{ok:!0,skipped:!0,attempts:[]};const s=d(t);if(!s)return T({baseUrl:t,serviceName:e,attempts:[],reason:`HTTP endpoint readiness could not parse ${t||"unknown endpoint"}`});const f=c(r.timeoutMs??o.TESTKIT_HTTP_ENDPOINT_PREFLIGHT_TIMEOUT_MS,3e4),m=c(r.attemptTimeoutMs??o.TESTKIT_HTTP_ENDPOINT_PREFLIGHT_ATTEMPT_TIMEOUT_MS,5e3),_=c(r.retryDelayMs??o.TESTKIT_HTTP_ENDPOINT_PREFLIGHT_RETRY_DELAY_MS,500),u=Date.now()+f,a=[];for(;Date.now()<u;){if(n?.isStopRequested()||i?.aborted)return T({baseUrl:t,serviceName:e,attempts:a,reason:`testkit run interrupted before HTTP endpoint readiness completed for ${t}`});const h=Math.max(1,u-Date.now()),p=await E(s,Math.min(m,h),i);if(a.push(p),p.ok)return{ok:!0,skipped:!1,attempts:a};await w(Math.min(_,Math.max(0,u-Date.now())),i)}return T({baseUrl:t,serviceName:e,attempts:a,reason:`HTTP endpoint for ${e||"unknown"} was not reachable at ${t}`})}function T({baseUrl:t,serviceName:e,attempts:n,reason:r}){const o=n.map(s=>s.error).filter(s=>!!s).slice(-3).join("; "),i=o?`${r}. Last connection failure(s): ${o}`:r;return{ok:!1,skipped:!1,reason:i,attempts:n,failureDetails:[{count:1,kind:"http_endpoint_readiness",key:"http_endpoint_readiness",title:"HTTP endpoint readiness failed",classification:"infra",message:i,service:e||null,endpoint:t}]}}function d(t){try{const e=new URL(t);if(!["http:","https:"].includes(e.protocol))return null;const n=Number(e.port||(e.protocol==="https:"?443:80));return!Number.isInteger(n)||n<=0||n>65535?null:{host:l(e.hostname),port:n}}catch{return null}}function c(t,e){const n=Number(t);return Number.isInteger(n)&&n>0?n:e}function l(t){return t.trim().toLowerCase().replace(/^\[(.*)\]$/u,"$1")}function w(t,e){return e?.aborted?Promise.resolve():new Promise(n=>{const r=setTimeout(o,t);function o(){clearTimeout(r),e?.removeEventListener("abort",o),n()}e?.addEventListener("abort",o,{once:!0})})}

package/dist/app/run/engine-evidence-persistence.d.ts

@@ -0,0 +1,39 @@
+import { type FileEvidenceBudget } from "../../evidence/file-evidence.js";
+import type { EngineEvidence } from "../../engines/api/index.js";
+import { type PersistedArtifactReference } from "../../evidence/index.js";
+import type { ScheduledTask } from "./scheduler/index.js";
+type EvidenceCategory = "artifacts" | "logs" | "metrics" | "native";
+type EvidencePersistenceMode = "observed" | "reconcile";
+export interface EvidenceLedger {
+    readonly countsByCategory: Readonly<Record<EvidenceCategory, Map<string, number>>>;
+    readonly fileEvidence: {
+        maximumBytes: number;
+        persistedBytes: number;
+    };
+}
+interface PersistEvidenceOptions {
+    artifactRoot: string;
+    evidence: EngineEvidence;
+    productDir: string;
+    scope: "invocation" | "task";
+    task: ScheduledTask;
+    fileEvidenceBudget?: FileEvidenceBudget;
+}
+export declare const MAX_ENGINE_FILE_EVIDENCE_BYTES: number;
+interface EvidencePersistenceContext {
+    artifactRoot: string;
+    errors: Error[];
+    ledger: EvidenceLedger;
+    mode: EvidencePersistenceMode;
+    productDir: string;
+    references: PersistedArtifactReference[];
+    scope: "invocation" | "task";
+    task: ScheduledTask;
+}
+export declare function persistEngineEvidence({ artifactRoot, evidence, productDir, scope, task, fileEvidenceBudget, }: Readonly<PersistEvidenceOptions>): PersistedArtifactReference[];
+export declare function persistTrackedEngineEvidence(evidence: Readonly<EngineEvidence>, context: EvidencePersistenceContext): void;
+export declare function createEvidenceLedger(maximumFileEvidenceBytes?: number): EvidenceLedger;
+export declare function requireTaskArtifacts(referencesByTaskId: ReadonlyMap<string, PersistedArtifactReference[]>, taskId: string): PersistedArtifactReference[];
+export declare function requireTaskEvidenceLedger(ledgersByTaskId: ReadonlyMap<string, EvidenceLedger>, taskId: string): EvidenceLedger;
+export declare function contextualError(message: string, cause: unknown): Error;
+export {};

package/dist/app/run/engine-evidence-persistence.js

@@ -0,0 +1 @@
+import{persistFileEvidence as m,fileEvidenceBudgetError as g}from"../../evidence/file-evidence.js";import{MAX_PERSISTED_FILE_ARTIFACT_BYTES as y,persistTaskArtifacts as p,persistTaskOutputArtifacts as E}from"../../evidence/index.js";export const MAX_ENGINE_FILE_EVIDENCE_BYTES=y;export function persistEngineEvidence({artifactRoot:e,evidence:t,productDir:i,scope:r,task:n,fileEvidenceBudget:a}){const o={engineId:n.engineId,file:n.file,id:n.id,profileId:n.profileId,serviceName:n.serviceName,suiteKey:n.suiteKey,suiteName:n.suiteName,testType:n.testType},u=m({artifactRoot:e,artifacts:t.artifacts,productDir:i,task:o,fileEvidenceBudget:a}),f=E(i,o,t.logs.map((c,d)=>({name:`${r}-engine-${c.stream}-${d.toString()}`,kind:`engine.${r}.log`,stream:c.stream,text:c.text}))),s=[...t.metrics.map((c,d)=>v(c,d,r)),...t.native===void 0?[]:[{name:`${r}-engine-native`,kind:`engine.${r}.native`,contentType:"application/json",summary:`${r} engine-native evidence`,emittedAt:new Date().toISOString(),data:t.native}]];return[...u,...f,...p(i,o,s)]}export function persistTrackedEngineEvidence(e,t){const i=[...e.artifacts.map(n=>({category:"artifacts",evidence:{artifacts:[n],logs:[],metrics:[]},value:n})),...e.logs.map(n=>({category:"logs",evidence:{artifacts:[],logs:[n],metrics:[]},value:n})),...e.metrics.map(n=>({category:"metrics",evidence:{artifacts:[],logs:[],metrics:[n]},value:n})),...e.native===void 0?[]:[{category:"native",evidence:{artifacts:[],logs:[],metrics:[],native:e.native},value:e.native}]],r=new Map;for(const n of i){let a;try{a=l(n.value)}catch(s){t.errors.push(contextualError(`Could not identify ${t.scope} engine ${n.category} evidence`,s));continue}const o=`${n.category}:${a}`,u=(r.get(o)??0)+1;r.set(o,u);const f=t.ledger.countsByCategory[n.category].get(a)??0;if(!(t.mode==="reconcile"&&u<=f))try{const s=persistEngineEvidence({artifactRoot:t.artifactRoot,evidence:n.evidence,productDir:t.productDir,scope:t.scope,task:t.task,...n.category==="artifacts"?{fileEvidenceBudget:$(t.ledger)}:{}});if(s.length===0)throw new Error("Evidence did not produce a persisted artifact");t.references.push(...s),t.ledger.countsByCategory[n.category].set(a,f+1)}catch(s){t.errors.push(contextualError(`Could not persist ${t.scope} engine ${n.category} evidence`,s))}}}export function createEvidenceLedger(e=MAX_ENGINE_FILE_EVIDENCE_BYTES){return{countsByCategory:{artifacts:new Map,logs:new Map,metrics:new Map,native:new Map},fileEvidence:{maximumBytes:Math.min(e,MAX_ENGINE_FILE_EVIDENCE_BYTES),persistedBytes:0}}}export function requireTaskArtifacts(e,t){const i=e.get(t);if(!i)throw new Error(`Artifact state is missing engine task ${t}`);return i}export function requireTaskEvidenceLedger(e,t){const i=e.get(t);if(!i)throw new Error(`Evidence state is missing engine task ${t}`);return i}export function contextualError(e,t){return new Error(`${e}: ${B(t).message}`,{cause:t})}function l(e){const t=JSON.stringify(e);if(typeof t!="string")throw new TypeError("Engine evidence entry must be JSON-serializable");return t}function v(e,t,i){return{name:`${i}-engine-metric-${t.toString()}`,kind:`engine.${i}.metric`,contentType:"application/json",summary:`${e.name}=${e.value.toString()}${e.unit?` ${e.unit}`:""}`,emittedAt:new Date().toISOString(),data:{name:e.name,value:e.value,...e.unit===void 0?{}:{unit:e.unit},...e.dimensions===void 0?{}:{dimensions:e.dimensions}}}}function $(e){return{consume(t){const i=e.fileEvidence.persistedBytes+t;if(i>e.fileEvidence.maximumBytes)throw g(e.fileEvidence.maximumBytes);e.fileEvidence.persistedBytes=i},maximumBytes(){return e.fileEvidence.maximumBytes},remainingBytes(){return e.fileEvidence.maximumBytes-e.fileEvidence.persistedBytes}}}function B(e){return e instanceof Error?e:new Error(String(e))}

package/dist/app/run/engine-execution-cleanup.d.ts

@@ -0,0 +1,8 @@
+import type { EngineTaskExecutionOutcome } from "./engine-execution.js";
+import type { EngineExecutionCleanupFailure } from "./engine-execution-failures.js";
+export interface PreparedNodeSetupCleanup {
+    cleanup: () => Promise<void>;
+    taskId: string;
+}
+export declare function cleanupPreparedNodeSetups(cleanupStack: readonly Readonly<PreparedNodeSetupCleanup>[]): Promise<EngineExecutionCleanupFailure[]>;
+export declare function applyConsumerNodeSetupCleanupFailures(completedOutcomesByTaskId: Map<string, EngineTaskExecutionOutcome>, cleanupFailures: readonly Readonly<EngineExecutionCleanupFailure>[]): void;

package/dist/app/run/engine-execution-cleanup.js

@@ -0,0 +1 @@
+import{getRuntimeNodeSetupCleanupFailures as i}from"./setup/runtime-node-setup.js";export async function cleanupPreparedNodeSetups(e){const s=[];for(const{cleanup:u,taskId:n}of[...e].reverse())try{await u()}catch(t){const r=i(t);r.length===0?s.push({error:l(t),owner:"testkit",taskId:n}):s.push(...r.map(o=>({...o,taskId:n})))}return s}export function applyConsumerNodeSetupCleanupFailures(e,s){const u=new Map;for(const n of s){if(n.owner!=="consumer")continue;const t=u.get(n.taskId)??[];t.push(n.error),u.set(n.taskId,t)}for(const[n,t]of u){const r=e.get(n);if(r===void 0)continue;const o=`Runtime node setup consumer cleanup failed: ${t.map(a=>a.message).join("; ")}`;e.set(n,{...r,error:r.error===null?o:`${r.error}; ${o}`,failureDetails:[...r.failureDetails,...t.map(c)],reason:null,status:"failed"})}}function c(e){return{actual:{owner:"consumer"},classification:"product",count:1,key:"runtime_node_setup_consumer_cleanup_failed",kind:"runtime-node-setup-cleanup",message:e.message,...e.stack===void 0?{}:{stack:e.stack},title:"Runtime node setup consumer cleanup failed"}}function l(e){return e instanceof Error?e:new Error(String(e))}