pi-helper-core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-21
+
+### Added
+
+- Initial extraction of the shared core from `pi-ros-helper` and `pi-python-helper`, which had each implemented the same envelope, runner, safety, validation, and staleness logic independently (`src/core/version.ts` was byte-identical; `src/core/result.ts` had already drifted).
+- `core/result.ts`: the shared response envelope with the `ok`/`attention` contract, `CORE_SCHEMA_VERSION`, and an ecosystem-neutral `ToolchainInfo` that replaces per-ecosystem metadata fields (`pythonVersion`, `rosDistro`). `createResultFactory(toolVersion)` binds the envelope to a package so a helper keeps its own call sites.
+- `core/runner.ts`: one bounded subprocess entry point with timeout, `AbortSignal`, output caps, process-group termination, and `isSpawnFailure` for "the command never started".
+- `core/safety.ts`: risk classification from command text. Universal rules (repository history, file system, containers, destructive SQL, pipe-to-shell) always apply; adapters add only their own package-manager rules.
+- `validation/evidence.ts`, `validation/tdd.ts`, `validation/bundle.ts`: the completion gates, parameterised by adapter-supplied labels and file classification. `summarizeValidation` treats a preview, an unexecuted step, and a run that executed zero tests as failures rather than as non-failures.
+- `build/staleness.ts`: generic "derived artifact older than its newest source" detection with adapter-supplied artifact specs.
+- `selection/select.ts`: the test-selection ranking with injected file classification and module naming. Signals shared by every candidate are discarded so a package-rooted test tree narrows instead of selecting the whole suite.
+- `adapter.ts`: the `EcosystemAdapter` seam and its supporting types.
+- `test/purity.test.ts`: fails the build if an ecosystem name appears in core executable code, or if the core imports anything outside itself and Node builtins.

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 wkqco
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,86 @@
+# pi-helper-core
+
+pi 언어 헬퍼 확장(`pi-ros-helper`, `pi-python-helper`, `pi-rust-helper`, …)이 공유하는 **생태계 중립 코어**입니다.
+
+## 왜 필요한가
+
+`pi-ros-helper`와 `pi-python-helper`는 같은 것을 각자 구현했습니다.
+
+- `src/core/version.ts` → **바이트 단위로 동일**
+- `src/core/result.ts` → 같은 envelope, 이미 **드리프트**(ROS에 `attention`/`CommandPreview.risk` 없음)
+- `src/core/{runner,safety}.ts`, `src/validation/{bundle,evidence,tdd}.ts`, `src/build/staleness.ts` → 양쪽에 중복
+
+확장을 하나 더 복사할 때마다 이 계약이 한 벌씩 늘어납니다. 이 패키지가 단일 진실입니다.
+
+## 무엇이 들어 있나
+
+| 모듈 | 내용 |
+|---|---|
+| `core/result.ts` | 응답 envelope, `ok`/`attention` 계약, 생태계 중립 `ToolchainInfo` |
+| `core/runner.ts` | 타임아웃·`AbortSignal`·출력 상한이 걸린 단일 서브프로세스 진입점 |
+| `core/safety.ts` | 명령 위험도 분류(universal 규칙 + 어댑터 규칙 주입) |
+| `validation/evidence.ts` | 완료 증거 게이트 |
+| `validation/tdd.ts` | 프로덕션 변경 ↔ 테스트 변경 연관 검사 |
+| `validation/bundle.ts` | 검증 번들 요약 게이트 |
+| `build/staleness.ts` | 파생 산출물이 소스보다 오래됐는지 판정 |
+| `selection/select.ts` | 테스트 선별 랭킹 알고리즘 |
+| `adapter.ts` | `EcosystemAdapter` 계약 |
+
+**들어 있지 않은 것**: 도구 등록(`registerTool` 호출 금지), 특정 생태계의 명령·매니페스트·출력 형식. `test/purity.test.ts`가 코어 소스에 생태계 이름이 들어오는 것을 막습니다.
+
+## 사용법
+
+기존 헬퍼는 로컬 shim 두 줄로 마이그레이션할 수 있습니다. 호출부는 바뀌지 않습니다.
+
+```ts
+// src/core/result.ts (헬퍼 쪽 shim)
+import { createResultFactory } from 'pi-helper-core';
+import { TOOL_VERSION } from './version.ts';
+
+export const { result, failure } = createResultFactory(TOOL_VERSION);
+export { warn, note } from 'pi-helper-core';
+export type { ToolResult, Diagnostic, CommandPreview, ToolchainInfo } from 'pi-helper-core';
+```
+
+어댑터는 생태계 지식만 채웁니다.
+
+```ts
+import { defineAdapter } from 'pi-helper-core';
+
+export const adapter = defineAdapter({
+  id: 'rust',
+  riskRules: [/* cargo 전용 규칙 */],
+  selectionSignals: {/* 파일 분류, 모듈명, 토큰 */},
+  resolveToolchain: async (ctx) => {/* ... */},
+  readProjectModel: async (ctx) => {/* ... */},
+  testCommand: (input, ctx) => {/* ... */},
+  parseTestOutput: (stdout, stderr) => {/* ... */},
+  diagnoseFailure: (output) => {/* ... */},
+  derivedArtifacts: () => [],
+  testDirectories: () => ['tests'],
+  checkCommand: (input, ctx) => {/* ... */},
+});
+```
+
+## 계약 (반드시 지킬 것)
+
+- `ok`는 **도구의 판정**입니다("도구가 실행됐다"가 아님). 문제를 찾으면 도구가 실패하지 않았어도 `ok: false`입니다.
+- `attention`은 **조치 필요 여부**입니다. `ok: false`이거나 warning/error가 있으면 `true`, `info`는 `false`.
+- `ok: false`에는 **항상 설명하는 진단**이 따라옵니다.
+- 프리뷰는 **절대 통과가 아닙니다**(`summarizeValidation`이 `preview: true`면 `ok: false`).
+- 실행 범위를 숨기지 않습니다. 워크스페이스에서 "테스트 통과"는 **무엇이 실제로 실행됐는지**와 함께여야 합니다(`TestReport.ranTargets`, `noTestsRan`).
+
+## 개발
+
+```bash
+npm install
+npm test              # 48 tests
+npm run typecheck
+npm run check         # test + typecheck + format:check + pack-check
+```
+
+## 상태
+
+- `0.1.0`, **아직 npm에 배포하지 않음**
+- TypeScript 소스를 그대로 export합니다(`exports: "./src/index.ts"`). pi 확장 생태계가 TS를 직접 로드하므로 빌드 단계를 두지 않습니다.
+- 소비자: `pi-rust-helper`(파일럿) → 검증 후 `pi-ros-helper`, `pi-python-helper` 순으로 마이그레이션 예정

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "pi-helper-core",
+  "version": "0.1.0",
+  "description": "Ecosystem-neutral core for pi language helper extensions: result envelope, bounded command runner, risk classification, completion gates, artifact staleness, and test selection",
+  "type": "module",
+  "license": "Apache-2.0",
+  "keywords": ["pi-package", "pi", "helper", "toolchain", "validation"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wkqco33/pi-helper-core.git"
+  },
+  "files": ["src", "README.md", "LICENSE", "CHANGELOG.md"],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "test:coverage": "tsx --test --experimental-test-coverage test/*.test.ts",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\" \"scripts/**/*.mjs\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\" \"scripts/**/*.mjs\"",
+    "pack-check": "node scripts/verify-pack.mjs",
+    "check": "npm test && npm run typecheck && npm run format:check && npm run pack-check"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "prettier": "^3.9.8",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,152 @@
+import type { CommandPreview, Diagnostic, Suggestion, ToolchainInfo } from './core/result.ts';
+import type { RiskRule } from './core/safety.ts';
+import type { StaleArtifactSpec } from './build/staleness.ts';
+import type { SelectionSignals } from './selection/select.ts';
+
+/**
+ * The seam between the shared core and one ecosystem.
+ *
+ * Only the methods a helper's implemented tools actually need must exist; the
+ * rest can land later. The interface is deliberately narrower than "everything
+ * a helper might want" so that a single pilot cannot freeze a wrong abstraction
+ * for the other ecosystems.
+ */
+
+export interface AdapterContext {
+  cwd: string;
+  projectRoot?: string;
+  signal?: AbortSignal;
+}
+
+export interface FailureFrame {
+  path: string;
+  line: number;
+  column?: number;
+  /** True for installed dependencies and toolchain internals. */
+  library: boolean;
+}
+
+export interface FailureDiagnosis {
+  /** Ecosystem-defined kind; `unknown` must mean "not classified". */
+  kind: string;
+  summary: string;
+  /** Error code or exception type, for example `E0599`. */
+  exceptionType?: string;
+  missingModule?: string;
+  missingExecutable?: string;
+  frames: FailureFrame[];
+  /** The frame the user should look at, which is never a library frame. */
+  firstUserFrame?: FailureFrame;
+  evidence: { message: string; file?: string; line?: number }[];
+  suggestions: Suggestion[];
+}
+
+export interface TestCounts {
+  passed: number;
+  failed: number;
+  errors: number;
+  skipped: number;
+  xfailed?: number;
+  xpassed?: number;
+  warnings?: number;
+}
+
+export interface TestFailure {
+  test: string;
+  message: string;
+  file?: string;
+  line?: number;
+}
+
+export interface TestReport {
+  executed: boolean;
+  exitCode: number | null;
+  timedOut: boolean;
+  truncated: boolean;
+  counts: TestCounts;
+  /**
+   * The units that actually ran. In a workspace, "tests passed" is only
+   * meaningful next to the list of members that were compiled and tested,
+   * because a root-level run often covers a subset.
+   */
+  ranTargets: string[];
+  /** True when documentation tests were part of the run. */
+  includedDocTests?: boolean;
+  /** True when the runner completed without executing a single test. */
+  noTestsRan: boolean;
+  /** True when no trustworthy summary could be parsed. */
+  incomplete: boolean;
+  summaryLine?: string;
+  failures: TestFailure[];
+}
+
+export interface ProjectPackage {
+  name: string;
+  version?: string;
+  manifest: string;
+  /** True when the package is a member of the workspace. */
+  member: boolean;
+  /** True when a bare workspace-level run covers this package. */
+  defaultMember?: boolean;
+  /** Declared minimum toolchain version, when the manifest carries one. */
+  minimumToolchain?: string;
+  detail?: Record<string, string>;
+}
+
+export interface ProjectModel {
+  root: string;
+  toolchain: ToolchainInfo;
+  packages: ProjectPackage[];
+  warnings: Diagnostic[];
+}
+
+/** A derived file that must be newer than the sources it describes. */
+export type DerivedArtifact = StaleArtifactSpec;
+
+export interface TestCommandInput {
+  /** Workspace members to restrict the run to. */
+  targets?: string[];
+  /** Individual files to run, when the runner accepts them directly. */
+  files?: string[];
+  /** Run tests for every target the manifest declares. */
+  allTargets?: boolean;
+  /** Include documentation tests, when the ecosystem has them. */
+  docTests?: boolean;
+  extraArgs?: string[];
+}
+
+export interface CheckCommandInput {
+  targets?: string[];
+  allTargets?: boolean;
+  /** Compile only, without producing final artifacts. */
+  extraArgs?: string[];
+}
+
+export interface EcosystemAdapter {
+  /** Ecosystem identifier, for example `rust`. */
+  readonly id: string;
+  /** Ecosystem-specific additions to the universal risk rules. */
+  readonly riskRules: RiskRule[];
+  /** File-classification and ranking signals for test selection. */
+  readonly selectionSignals: SelectionSignals;
+  /** Tdd checkpoint signals; defaults to the selection signals when omitted. */
+  readonly tddSignals?: import('./validation/tdd.ts').TddSignals;
+
+  resolveToolchain(ctx: AdapterContext): Promise<ToolchainInfo>;
+  readProjectModel(ctx: AdapterContext): Promise<ProjectModel>;
+
+  testCommand(input: TestCommandInput, ctx: AdapterContext): CommandPreview;
+  checkCommand(input: CheckCommandInput, ctx: AdapterContext): CommandPreview;
+  parseTestOutput(stdout: string, stderr: string): TestReport;
+  diagnoseFailure(output: string, model?: ProjectModel): FailureDiagnosis;
+
+  /** Derived artifacts worth a staleness comparison; may be empty. */
+  derivedArtifacts(model: ProjectModel): DerivedArtifact[];
+  /** Directories the runner collects tests from. */
+  testDirectories(model: ProjectModel): string[];
+}
+
+/** Identity helper that preserves literal types when defining an adapter. */
+export function defineAdapter<T extends EcosystemAdapter>(adapter: T): T {
+  return adapter;
+}

package/src/build/staleness.ts

@@ -0,0 +1,147 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface StaleArtifact {
+  code: string;
+  message: string;
+  path: string;
+  artifactMtimeMs?: number;
+  newestSource?: { path: string; mtimeMs: number };
+}
+
+export interface StalenessReport {
+  stale: boolean;
+  artifacts: StaleArtifact[];
+  /** Populated when the check could not be completed, so `stale: false` is not overclaimed. */
+  incompleteReason?: string;
+}
+
+/** One derived file that must be newer than the sources it describes. */
+export interface StaleArtifactSpec {
+  /** File name relative to the project root. */
+  name: string;
+  code: string;
+  /** What the file holds, used in the message (`coverage results`). */
+  describe: string;
+}
+
+export interface StalenessSpec {
+  /** Extensions that count as source, including the dot (`.py`, `.rs`). */
+  sourceExtensions: string[];
+  artifacts: StaleArtifactSpec[];
+  /** Directories that never hold sources worth comparing. */
+  ignoredDirectories: ReadonlySet<string>;
+  maxWalkedFiles?: number;
+}
+
+/** Directories that are never source in any ecosystem. */
+export const UNIVERSAL_IGNORED_DIRECTORIES: ReadonlySet<string> = new Set([
+  '.git',
+  'node_modules',
+  '__pycache__',
+  '.pytest_cache',
+  '.mypy_cache',
+  '.ruff_cache',
+  '.tox',
+  '.nox',
+  '.eggs',
+  'build',
+  'dist',
+]);
+
+const DEFAULT_MAX_WALKED_FILES = 5000;
+
+async function mtimeMs(path: string): Promise<number | undefined> {
+  try {
+    return (await stat(path)).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+async function newestSource(
+  root: string,
+  spec: StalenessSpec,
+): Promise<{ path: string; mtimeMs: number } | undefined> {
+  let newest: { path: string; mtimeMs: number } | undefined;
+  let visited = 0;
+  const maxFiles = spec.maxWalkedFiles ?? DEFAULT_MAX_WALKED_FILES;
+  const ignored = new Set([...UNIVERSAL_IGNORED_DIRECTORIES, ...spec.ignoredDirectories]);
+  const stack = [root];
+  while (stack.length > 0) {
+    const directory = stack.pop() as string;
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch {
+      // A single unreadable directory must not abort the whole scan.
+      continue;
+    }
+    for (const entry of entries) {
+      if (visited > maxFiles) return newest;
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (ignored.has(entry.name)) continue;
+        stack.push(path);
+      } else if (entry.isFile() && spec.sourceExtensions.some((ext) => entry.name.endsWith(ext))) {
+        visited += 1;
+        const modified = await mtimeMs(path);
+        if (modified === undefined) continue;
+        if (!newest || modified > newest.mtimeMs) newest = { path, mtimeMs: modified };
+      }
+    }
+  }
+  return newest;
+}
+
+/**
+ * Detect a derived artifact that predates the sources it claims to describe.
+ *
+ * Bytecode caches and build fingerprints are invalidated automatically by most
+ * toolchains, so the artifacts that matter are the ones a tool writes and then
+ * quotes later (a coverage report, a generated binding). Quoting one of those
+ * after the sources changed is how a stale number becomes a false claim.
+ *
+ * When the check cannot be completed the report says why instead of returning a
+ * clean `stale: false`.
+ */
+export async function detectStaleArtifacts(
+  root: string,
+  spec: StalenessSpec,
+): Promise<StalenessReport> {
+  const artifacts: StaleArtifact[] = [];
+  let newest: { path: string; mtimeMs: number } | undefined;
+  try {
+    newest = await newestSource(root, spec);
+  } catch (error) {
+    return {
+      stale: false,
+      artifacts,
+      incompleteReason: `Source scan failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  if (!newest) {
+    return {
+      stale: false,
+      artifacts,
+      incompleteReason: `No source file (${spec.sourceExtensions.join(', ')}) was found.`,
+    };
+  }
+
+  for (const artifact of spec.artifacts) {
+    const path = join(root, artifact.name);
+    const modified = await mtimeMs(path);
+    if (modified === undefined) continue;
+    if (modified < newest.mtimeMs) {
+      artifacts.push({
+        code: artifact.code,
+        message: `${artifact.name} was written before ${newest.path} changed; ${artifact.describe} do not describe the current sources.`,
+        path,
+        artifactMtimeMs: modified,
+        newestSource: newest,
+      });
+    }
+  }
+
+  return { stale: artifacts.length > 0, artifacts };
+}

package/src/core/result.ts

@@ -0,0 +1,205 @@
+/**
+ * The single response contract every helper tool returns, so an agent can rely
+ * on one shape regardless of which ecosystem the helper targets.
+ *
+ * Nothing here may mention a specific ecosystem: the fields are the union of
+ * what a Python, ROS, Rust, Go, or Flutter helper needs, and anything else an
+ * ecosystem requires goes into `metadata.detail` rather than into a new field.
+ */
+
+/**
+ * Bumped when the envelope's shape changes. A consumer that pins a helper and
+ * this library independently can compare it and refuse a document it does not
+ * understand, the same way a scanner protocol version works.
+ */
+export const CORE_SCHEMA_VERSION = 1;
+
+export type Severity = 'info' | 'warning' | 'error';
+
+/**
+ * How dangerous running a command is. `read` is safe to run automatically;
+ * `mutating` and `irreversible` require explicit opt-in from the caller.
+ */
+export type CommandRisk = 'read' | 'mutating' | 'irreversible';
+
+export interface Diagnostic {
+  code?: string;
+  message: string;
+  severity: Severity;
+  path?: string;
+  line?: number;
+}
+
+export interface Evidence {
+  kind: string;
+  message?: string;
+  [key: string]: unknown;
+}
+
+export interface Suggestion {
+  message: string;
+  confidence?: 'low' | 'medium' | 'high';
+  command?: string;
+}
+
+export interface CommandPreview {
+  executable: string;
+  args: string[];
+  cwd?: string;
+  /** Risk classification for the command; `read` commands never change state. */
+  risk?: CommandRisk;
+}
+
+/**
+ * Ecosystem-neutral description of the toolchain a helper actually inspected.
+ *
+ * This replaces per-ecosystem metadata fields (`pythonVersion`, `rosDistro`):
+ * a consumer reads `toolchain.kind` and `toolchain.version` without knowing
+ * which helper produced the response.
+ */
+export interface ToolchainInfo {
+  /** Ecosystem identifier, for example `rust`, `python`, or `ros`. */
+  kind: string;
+  /** Version of the toolchain that would run commands. */
+  version?: string;
+  /**
+   * How the toolchain was located, so a caller can tell a project-local
+   * environment from whatever happened to be on `PATH`.
+   */
+  source?: 'project' | 'path' | 'override' | 'unknown';
+  /** Target triple, platform string, or distribution name. */
+  host?: string;
+  /** Ecosystem-specific extras that do not deserve a shared field. */
+  detail?: Record<string, string>;
+}
+
+export interface ToolMetadata {
+  toolVersion: string;
+  cwd: string;
+  durationMs: number;
+  truncated: boolean;
+  projectRoot?: string;
+  toolchain?: ToolchainInfo;
+  /** Escape hatch for ecosystem-specific metadata that is not shared. */
+  detail?: Record<string, unknown>;
+}
+
+export interface ToolResult<T = unknown> {
+  /**
+   * The tool's own verdict, not "the tool ran". `true` means the question this
+   * tool asks was answered affirmatively: the project state is acceptable, the
+   * command succeeded, or the gate may proceed. A diagnostic tool that finds a
+   * problem therefore returns `ok: false` without the tool itself having
+   * failed. Read `attention` for "must the caller act".
+   */
+  ok: boolean;
+  /**
+   * `true` when the caller must act before proceeding: the tool failed, or it
+   * emitted a warning or an error. An `info` diagnostic is informational by
+   * definition and does not set this. Derived from `ok`, `warnings`, and
+   * `errors` unless a tool sets it explicitly, so `ok: false` always implies
+   * `attention: true` and no diagnostic is silently dropped. This is the field
+   * to read when the question is "do I need to do something".
+   */
+  attention: boolean;
+  summary: string;
+  data?: T;
+  evidence: Evidence[];
+  warnings: Diagnostic[];
+  errors: Diagnostic[];
+  suggestions: Suggestion[];
+  commands?: CommandPreview[];
+  metadata: ToolMetadata;
+}
+
+/**
+ * Values a tool supplies. `attention` is normally derived, and `metadata` is
+ * assembled by the factory, so neither is expected from the caller.
+ */
+export type ResultInput<T = unknown> = Omit<ToolResult<T>, 'metadata' | 'attention'> & {
+  attention?: boolean;
+  truncated?: boolean;
+  projectRoot?: string;
+  toolchain?: ToolchainInfo;
+  detail?: Record<string, unknown>;
+};
+
+/**
+ * An `info` diagnostic records a fact; only a warning or an error asks the
+ * caller to do something. Keeping them apart stops a purely informational note
+ * from raising `attention`.
+ */
+export function isActionable(value: { warnings: Diagnostic[]; errors: Diagnostic[] }): boolean {
+  return [...value.warnings, ...value.errors].some((entry) => entry.severity !== 'info');
+}
+
+export interface ResultFactory {
+  result: <T>(cwd: string, startedAt: number, value: ResultInput<T>) => ToolResult<T>;
+  failure: (
+    cwd: string,
+    startedAt: number,
+    message: string,
+    code: string,
+    details?: Partial<ResultInput>,
+  ) => ToolResult;
+  toolVersion: string;
+}
+
+/**
+ * Bind the envelope to one package's version.
+ *
+ * A helper keeps a two-line local shim so its own modules keep importing
+ * `result`/`failure` unchanged:
+ *
+ * ```ts
+ * export const { result, failure } = createResultFactory(TOOL_VERSION);
+ * export type { ToolResult, Diagnostic, CommandPreview } from 'pi-helper-core';
+ * ```
+ */
+export function createResultFactory(toolVersion: string): ResultFactory {
+  const result = <T>(cwd: string, startedAt: number, value: ResultInput<T>): ToolResult<T> => {
+    const { attention, truncated, projectRoot, toolchain, detail, ...rest } = value;
+    return {
+      ...rest,
+      attention: attention ?? (!rest.ok || isActionable(rest)),
+      metadata: {
+        toolVersion,
+        cwd,
+        durationMs: Date.now() - startedAt,
+        truncated: truncated ?? false,
+        projectRoot,
+        toolchain,
+        detail,
+      },
+    } as ToolResult<T>;
+  };
+
+  const failure = (
+    cwd: string,
+    startedAt: number,
+    message: string,
+    code: string,
+    details?: Partial<ResultInput>,
+  ): ToolResult =>
+    result(cwd, startedAt, {
+      ok: false,
+      summary: message,
+      evidence: [],
+      warnings: [],
+      errors: [{ code, message, severity: 'error' }],
+      suggestions: [],
+      ...details,
+    });
+
+  return { result, failure, toolVersion };
+}
+
+/** Shared helper so diagnostics never lose their code when built inline. */
+export function warn(code: string, message: string, path?: string, line?: number): Diagnostic {
+  return { code, message, severity: 'warning', path, line };
+}
+
+/** Shared helper for informational notes, which never raise `attention`. */
+export function note(code: string, message: string, path?: string, line?: number): Diagnostic {
+  return { code, message, severity: 'info', path, line };
+}