@noctcore/harness 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,136 @@
+export { C as CheckStatus, M as ManifestOutcome, P as PlannedCheck, a as StructureLockCheck, b as StructureLockResult } from './run-B6_KI2bV.js';
+
+/**
+ * The PORTABLE lint-meta contract — the types a target repo's generated
+ * `lint-meta-rule` artifacts implement and import from `@noctcore/harness`.
+ *
+ * This is an owned COPY of the Nightcore-internal `tools/lint-meta/types.ts`
+ * (the engine that enforces what ESLint cannot reach: cross-file contracts,
+ * non-JS files, config parity). It is reproduced here, not imported, so the
+ * published package carries the whole contract with ZERO runtime dependency on
+ * the monorepo — a generated rule in a stranger's repo does
+ * `import type { IMetaRule } from '@noctcore/harness'` and nothing else.
+ *
+ * Rules are pure functions of an {@link IMetaCtx} and return {@link IViolation}s;
+ * the runner exits non-zero when any `ciCritical` rule reports one (or throws).
+ */
+interface IMetaCtx {
+    /** Absolute repo root the rule reads relative to. */
+    readonly root: string;
+    /** Read a repo-relative file (LF-normalized), or `null` if it does not exist. */
+    read(rel: string): string | null;
+    /** Whether a repo-relative path exists. */
+    exists(rel: string): boolean;
+    /** Glob repo-relative paths (cwd = {@link root}). */
+    glob(pattern: string): string[];
+    /** Run a shell command at {@link root}; never throws. */
+    exec(cmd: string): {
+        code: number;
+        stdout: string;
+        stderr: string;
+    };
+}
+interface IViolation {
+    file: string;
+    rule: string;
+    message: string;
+    /**
+     * 1-indexed source location, when the rule can pinpoint one. Optional and
+     * additive: the text reporter ignores it (it surfaces `file`/`rule`/`message`
+     * only), so a rule may omit it.
+     */
+    line?: number;
+    column?: number;
+}
+interface IMetaRule {
+    id: string;
+    category: 'config' | 'source-text' | 'supply-chain' | 'ci' | 'testing';
+    description: string;
+    /** When true, a violation fails CI (the runner exits non-zero). */
+    ciCritical?: boolean;
+    run(ctx: IMetaCtx): IViolation[];
+    /**
+     * Ratcheting rules implement this to snapshot the CURRENT offenders as a frozen
+     * baseline (a flat `metric-key → number` map). A rule's `run` then grandfathers
+     * any offender still within its recorded value (see `baseline.ts`). Omit for
+     * strict rules.
+     */
+    baseline?(ctx: IMetaCtx): Record<string, number>;
+}
+
+/**
+ * The generic lint-meta ratchet — a faithful port of `tools/lint-meta/baseline.ts`.
+ *
+ * A baseline is a committed `<baselineDir>/<rule-id>.json` — a flat `key → number`
+ * map freezing today's offenders at their current metric. The ratchet is one-way:
+ * an offender that is recorded AND has not grown past its frozen value is
+ * grandfathered (suppressed); a NEW offender, or a recorded one that GREW, is a
+ * live violation. As each offender is fixed, its entry is deleted (or lowered),
+ * never raised — the frozen debt only shrinks.
+ *
+ * The `key` is opaque to this module: a rule with more than one metric family
+ * namespaces its keys (`size:<file>`, `manifest:<file>`) so one flat map serves both.
+ *
+ * The only portability change from the internal engine is the baseline HOME: the
+ * Nightcore engine hardcodes `tools/lint-meta/baselines/`, whereas a portable rule
+ * ships its baselines under {@link DEFAULT_BASELINE_DIR} (overridable per call).
+ */
+
+/** Where a portable rule's committed baselines live, relative to the repo root. */
+declare const DEFAULT_BASELINE_DIR = ".nightcore/lint-meta/baselines";
+/** Load a rule's committed baseline, or `{}` when none exists yet. */
+declare function loadBaseline(ctx: IMetaCtx, ruleId: string, baselineDir?: string): Record<string, number>;
+/**
+ * Whether `current` for `key` is grandfathered by `baseline`: recorded AND not
+ * grown past the frozen value. A key absent from the baseline is never
+ * grandfathered (a new offender always fails); a recorded key whose current value
+ * is `<=` its record passes (the ratchet permits staying same-or-shrinking).
+ */
+declare function isGrandfathered(baseline: Record<string, number>, key: string, current: number): boolean;
+/** Serialize a baseline map with sorted keys for a stable, diff-friendly file. */
+declare function serializeBaseline(map: Record<string, number>): string;
+
+/**
+ * Public type surface of `@noctcore/harness`. Exposes the
+ * `.nightcore/harness.json` manifest shape, the `StructureLockResult`-shaped
+ * verdict the runner emits (camelCase, wire-compatible with the Rust
+ * `StructureLockResult` / `StructureLockCheck`), AND the portable lint-meta
+ * contract (`IMetaRule` / `IMetaCtx` / `IViolation`) a target repo's generated
+ * `lint-meta-rule` artifacts implement.
+ *
+ * This barrel exists so generated artifacts and downstream tooling can
+ * `import type` from the published package.
+ */
+
+/** One check as declared in `.nightcore/harness.json`. */
+interface HarnessManifestCheck {
+    /** The logical check name (e.g. `folder-per-component`). */
+    name: string;
+    /** The harness kind (e.g. `lint-plugin`, `ast-grep`). Free-form on the wire. */
+    kind: string;
+    /** The exact command line to run (e.g. `npx eslint .`). */
+    command?: string;
+    /** Optional config path for the underlying tool (informational). */
+    configPath?: string;
+    /** Per-check wall-clock timeout in milliseconds (`> 0`, else the default). */
+    timeoutMs?: number;
+    /** Whether the check participates in the gate. Defaults to `true`. */
+    enabled?: boolean;
+}
+/** The `.nightcore/harness.json` manifest the runner reads. */
+interface HarnessManifest {
+    /**
+     * The manifest MAJOR schema version. Absent ⇒ treated as `1`. A higher MAJOR
+     * than the runner supports reds the build (upgrade the runner).
+     */
+    schemaVersion?: number;
+    /** The checks the runner enforces. Absent/empty ⇒ nothing to enforce. */
+    checks?: HarnessManifestCheck[];
+    /**
+     * The Nightcore agent-runtime policy block. Carried for Nightcore-driven
+     * consumers; the CI runner does not interpret it.
+     */
+    policy?: Record<string, unknown>;
+}
+
+export { DEFAULT_BASELINE_DIR, type HarnessManifest, type HarnessManifestCheck, type IMetaCtx, type IMetaRule, type IViolation, isGrandfathered, loadBaseline, serializeBaseline };

package/dist/index.js

@@ -0,0 +1,34 @@
+// src/lint-meta/baseline.ts
+var DEFAULT_BASELINE_DIR = ".nightcore/lint-meta/baselines";
+function loadBaseline(ctx, ruleId, baselineDir = DEFAULT_BASELINE_DIR) {
+  const raw = ctx.read(`${baselineDir}/${ruleId}.json`);
+  if (raw === null) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return isNumberMap(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function isGrandfathered(baseline, key, current) {
+  const frozen = baseline[key];
+  return frozen !== void 0 && current <= frozen;
+}
+function serializeBaseline(map) {
+  const sorted = {};
+  for (const key of Object.keys(map).sort()) {
+    const value = map[key];
+    if (value !== void 0) sorted[key] = value;
+  }
+  return `${JSON.stringify(sorted, null, 2)}
+`;
+}
+function isNumberMap(v) {
+  return typeof v === "object" && v !== null && Object.values(v).every((n) => typeof n === "number");
+}
+export {
+  DEFAULT_BASELINE_DIR,
+  isGrandfathered,
+  loadBaseline,
+  serializeBaseline
+};

package/dist/run-B6_KI2bV.d.cts

@@ -0,0 +1,93 @@
+/** A check resolved into the program + args to spawn. */
+interface PlannedCheck {
+    name: string;
+    /** The manifest `kind` wire string, carried through verbatim to the result. */
+    kind: string;
+    /** The exact command line, retained for the result + fix instruction. */
+    command: string;
+    program: string;
+    args: string[];
+    /** The resolved per-check wall-clock timeout in milliseconds. */
+    timeoutMs: number;
+}
+/**
+ * The result of loading a manifest. `no-config` (exit 0, opt-in-by-presence),
+ * `schema-too-new` (exit non-zero, upgrade the runner), or `ready` with the
+ * planned checks (possibly empty ⇒ trivially passing).
+ */
+type ManifestOutcome = {
+    kind: 'no-config';
+} | {
+    kind: 'schema-too-new';
+    found: number;
+} | {
+    kind: 'ready';
+    checks: PlannedCheck[];
+};
+/** Reads an absolute path, returning its contents or `null` if unreadable. */
+type FileReader = (absolutePath: string) => string | null;
+
+/**
+ * The runner + reporting — a faithful Node port of the in-process Rust runner
+ * (`workflow/gauntlet_project/runner.rs`), minus the Nightcore-orchestration-only
+ * machinery (retry-once/flaky, the security-critical no-retry exclusion, drift
+ * substrates, and the task verify-command append — none of which has a CI
+ * meaning). Statuses are therefore only `passed` / `failed`.
+ *
+ * FULL-RUN semantics (matching the live Rust runner, NOT the spec's stale
+ * stop-at-first text): every enabled check runs and records its own outcome, so
+ * a human reading CI sees the WHOLE failure set at once instead of one failure
+ * per pushed round. Each check is wall-clock BOUNDED by its `timeoutMs`; a
+ * timeout is a FAILED check (fail-closed — never a silent pass). `passed` is
+ * false iff ANY check failed; `failedCheck` names the FIRST failed check
+ * (back-compat).
+ *
+ * Pure over an injected {@link SpawnFn} so it is unit-testable without spawning.
+ */
+
+/** A check outcome. `skipped`/`flaky` from the in-process runner are dropped. */
+type CheckStatus = 'passed' | 'failed';
+/**
+ * The outcome of one structure-lock check. Wire-compatible (camelCase) with the
+ * Rust `StructureLockCheck` — `exitCode` / `output` / `durationMs` are omitted
+ * when absent.
+ */
+interface StructureLockCheck {
+    name: string;
+    kind: string;
+    command: string;
+    status: CheckStatus;
+    exitCode?: number;
+    output?: string;
+    durationMs?: number;
+}
+/**
+ * The structured verdict. Wire-compatible (camelCase) with the Rust
+ * `StructureLockResult` — `failedCheck` is omitted when everything passed.
+ */
+interface StructureLockResult {
+    passed: boolean;
+    checks: StructureLockCheck[];
+    failedCheck?: string;
+}
+/** The normalized result of one spawn — a subset of Node's `spawnSync` return. */
+interface SpawnResult {
+    /** Process exit code, or `null` when the process did not exit normally. */
+    status: number | null;
+    /** The signal that terminated the process, if any (e.g. a timeout kill). */
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+    /** Set when the process could not be launched or was timed out. */
+    error?: {
+        code?: string;
+        message?: string;
+    };
+}
+/** Runs `program args` in `cwd`, bounded by `timeoutMs`. Must never throw. */
+type SpawnFn = (program: string, args: string[], options: {
+    cwd: string;
+    timeoutMs: number;
+}) => SpawnResult;
+
+export type { CheckStatus as C, FileReader as F, ManifestOutcome as M, PlannedCheck as P, SpawnFn as S, StructureLockCheck as a, StructureLockResult as b };

package/dist/run-B6_KI2bV.d.ts

@@ -0,0 +1,93 @@
+/** A check resolved into the program + args to spawn. */
+interface PlannedCheck {
+    name: string;
+    /** The manifest `kind` wire string, carried through verbatim to the result. */
+    kind: string;
+    /** The exact command line, retained for the result + fix instruction. */
+    command: string;
+    program: string;
+    args: string[];
+    /** The resolved per-check wall-clock timeout in milliseconds. */
+    timeoutMs: number;
+}
+/**
+ * The result of loading a manifest. `no-config` (exit 0, opt-in-by-presence),
+ * `schema-too-new` (exit non-zero, upgrade the runner), or `ready` with the
+ * planned checks (possibly empty ⇒ trivially passing).
+ */
+type ManifestOutcome = {
+    kind: 'no-config';
+} | {
+    kind: 'schema-too-new';
+    found: number;
+} | {
+    kind: 'ready';
+    checks: PlannedCheck[];
+};
+/** Reads an absolute path, returning its contents or `null` if unreadable. */
+type FileReader = (absolutePath: string) => string | null;
+
+/**
+ * The runner + reporting — a faithful Node port of the in-process Rust runner
+ * (`workflow/gauntlet_project/runner.rs`), minus the Nightcore-orchestration-only
+ * machinery (retry-once/flaky, the security-critical no-retry exclusion, drift
+ * substrates, and the task verify-command append — none of which has a CI
+ * meaning). Statuses are therefore only `passed` / `failed`.
+ *
+ * FULL-RUN semantics (matching the live Rust runner, NOT the spec's stale
+ * stop-at-first text): every enabled check runs and records its own outcome, so
+ * a human reading CI sees the WHOLE failure set at once instead of one failure
+ * per pushed round. Each check is wall-clock BOUNDED by its `timeoutMs`; a
+ * timeout is a FAILED check (fail-closed — never a silent pass). `passed` is
+ * false iff ANY check failed; `failedCheck` names the FIRST failed check
+ * (back-compat).
+ *
+ * Pure over an injected {@link SpawnFn} so it is unit-testable without spawning.
+ */
+
+/** A check outcome. `skipped`/`flaky` from the in-process runner are dropped. */
+type CheckStatus = 'passed' | 'failed';
+/**
+ * The outcome of one structure-lock check. Wire-compatible (camelCase) with the
+ * Rust `StructureLockCheck` — `exitCode` / `output` / `durationMs` are omitted
+ * when absent.
+ */
+interface StructureLockCheck {
+    name: string;
+    kind: string;
+    command: string;
+    status: CheckStatus;
+    exitCode?: number;
+    output?: string;
+    durationMs?: number;
+}
+/**
+ * The structured verdict. Wire-compatible (camelCase) with the Rust
+ * `StructureLockResult` — `failedCheck` is omitted when everything passed.
+ */
+interface StructureLockResult {
+    passed: boolean;
+    checks: StructureLockCheck[];
+    failedCheck?: string;
+}
+/** The normalized result of one spawn — a subset of Node's `spawnSync` return. */
+interface SpawnResult {
+    /** Process exit code, or `null` when the process did not exit normally. */
+    status: number | null;
+    /** The signal that terminated the process, if any (e.g. a timeout kill). */
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+    /** Set when the process could not be launched or was timed out. */
+    error?: {
+        code?: string;
+        message?: string;
+    };
+}
+/** Runs `program args` in `cwd`, bounded by `timeoutMs`. Must never throw. */
+type SpawnFn = (program: string, args: string[], options: {
+    cwd: string;
+    timeoutMs: number;
+}) => SpawnResult;
+
+export type { CheckStatus as C, FileReader as F, ManifestOutcome as M, PlannedCheck as P, SpawnFn as S, StructureLockCheck as a, StructureLockResult as b };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@noctcore/harness",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Portable Structure-Lock runner — enforces a repo's .nightcore/harness.json checks in any CI, with no Nightcore install.",
+  "license": "MIT",
+  "homepage": "https://github.com/noctcore/nightcore/tree/main/packages/harness#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noctcore/nightcore.git",
+    "directory": "packages/harness"
+  },
+  "bugs": {
+    "url": "https://github.com/noctcore/nightcore/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "harness": "./dist/cli.js"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/cli.ts src/index.ts --format esm,cjs --dts --clean",
+    "prepack": "npm run build",
+    "check-types": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.0",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.0"
+  }
+}