@habitat-ai/resource-rule-evaluation 0.2.0

package/dist/contract.d.ts

@@ -0,0 +1,73 @@
+import type { Effect } from "effect";
+import { type Static, Type } from "typebox";
+/** Maximum detail retained by one rule-evaluation failure. */
+export declare const MAX_RULE_EVALUATION_FAILURE_DETAIL = 4096;
+/** Structural schema for one source position reported by an evaluator. */
+export declare const RuleEvaluationPositionSchema: Type.TObject<{
+    line: Type.TReadonly<Type.TInteger>;
+    column: Type.TReadonly<Type.TInteger>;
+    offset: Type.TReadonly<Type.TInteger>;
+}>;
+/** Structural schema for one provider-neutral evaluation finding. */
+export declare const RuleEvaluationFindingSchema: Type.TObject<{
+    path: Type.TReadonly<Type.TString>;
+    start: Type.TReadonly<Type.TObject<{
+        line: Type.TReadonly<Type.TInteger>;
+        column: Type.TReadonly<Type.TInteger>;
+        offset: Type.TReadonly<Type.TInteger>;
+    }>>;
+    end: Type.TReadonly<Type.TObject<{
+        line: Type.TReadonly<Type.TInteger>;
+        column: Type.TReadonly<Type.TInteger>;
+        offset: Type.TReadonly<Type.TInteger>;
+    }>>;
+    message: Type.TReadonly<Type.TUnion<[Type.TString, Type.TNull]>>;
+}>;
+/** Structural schema for one already-resolved evaluation request. */
+export declare const RuleEvaluationRequestSchema: Type.TObject<{
+    program: Type.TReadonly<Type.TString>;
+    subjectPaths: Type.TReadonly<Type.TImmutable<Type.TArray<Type.TString>>>;
+}>;
+/** Structural schema for one completed evaluation. */
+export declare const RuleEvaluationResultSchema: Type.TObject<{
+    findings: Type.TReadonly<Type.TImmutable<Type.TArray<Type.TObject<{
+        path: Type.TReadonly<Type.TString>;
+        start: Type.TReadonly<Type.TObject<{
+            line: Type.TReadonly<Type.TInteger>;
+            column: Type.TReadonly<Type.TInteger>;
+            offset: Type.TReadonly<Type.TInteger>;
+        }>>;
+        end: Type.TReadonly<Type.TObject<{
+            line: Type.TReadonly<Type.TInteger>;
+            column: Type.TReadonly<Type.TInteger>;
+            offset: Type.TReadonly<Type.TInteger>;
+        }>>;
+        message: Type.TReadonly<Type.TUnion<[Type.TString, Type.TNull]>>;
+    }>>>>;
+}>;
+/** Provider-neutral mechanical failure reasons for one evaluation attempt. */
+export declare const RuleEvaluationFailureReasonSchema: Type.TUnion<[Type.TLiteral<"InvalidInput">, Type.TLiteral<"SetupFailed">, Type.TLiteral<"ExecutionFailed">, Type.TLiteral<"TimedOut">, Type.TLiteral<"InvalidOutput">]>;
+/** Structural schema for one bounded typed evaluation failure. */
+export declare const RuleEvaluationFailureSchema: Type.TObject<{
+    _tag: Type.TReadonly<Type.TLiteral<"RuleEvaluationFailure">>;
+    reason: Type.TReadonly<Type.TUnion<[Type.TLiteral<"InvalidInput">, Type.TLiteral<"SetupFailed">, Type.TLiteral<"ExecutionFailed">, Type.TLiteral<"TimedOut">, Type.TLiteral<"InvalidOutput">]>>;
+    detail: Type.TReadonly<Type.TString>;
+}>;
+/** One evaluator-reported source position. */
+export type RuleEvaluationPosition = Static<typeof RuleEvaluationPositionSchema>;
+/** One provider-neutral finding. */
+export type RuleEvaluationFinding = Static<typeof RuleEvaluationFindingSchema>;
+/** One already-resolved evaluation request. */
+export type RuleEvaluationRequest = Static<typeof RuleEvaluationRequestSchema>;
+/** One completed evaluation result. */
+export type RuleEvaluationResult = Static<typeof RuleEvaluationResultSchema>;
+/** One provider-neutral mechanical failure reason. */
+export type RuleEvaluationFailureReason = Static<typeof RuleEvaluationFailureReasonSchema>;
+/** One typed mechanical evaluation failure. */
+export type RuleEvaluationFailure = Static<typeof RuleEvaluationFailureSchema>;
+/** Checks an unknown value against the complete rule-evaluation failure contract. */
+export declare function isRuleEvaluationFailure(input: unknown): input is RuleEvaluationFailure;
+/** Provider-neutral capability for evaluating one resolved program. */
+export interface RuleEvaluationResource<R = never> {
+    readonly evaluate: (input: RuleEvaluationRequest) => Effect.Effect<RuleEvaluationResult, RuleEvaluationFailure, R>;
+}

package/dist/contract.js

@@ -0,0 +1,76 @@
+import { ReadonlyObject, Type } from "typebox";
+import Schema from "typebox/schema";
+/** Maximum detail retained by one rule-evaluation failure. */
+export const MAX_RULE_EVALUATION_FAILURE_DETAIL = 4_096;
+const NonEmptyStringSchema = Type.String({
+    minLength: 1,
+});
+/** Structural schema for one source position reported by an evaluator. */
+export const RuleEvaluationPositionSchema = ReadonlyObject(Type.Object({
+    line: Type.Integer({
+        minimum: 1,
+        description: "One-based source line",
+    }),
+    column: Type.Integer({
+        minimum: 1,
+        description: "One-based source column",
+    }),
+    offset: Type.Integer({
+        minimum: 0,
+        description: "Zero-based evaluator-native source offset",
+    }),
+}), { additionalProperties: false });
+/** Structural schema for one provider-neutral evaluation finding. */
+export const RuleEvaluationFindingSchema = ReadonlyObject(Type.Object({
+    path: Type.String({
+        minLength: 1,
+        description: "Subject path reported by the evaluator",
+    }),
+    start: RuleEvaluationPositionSchema,
+    end: RuleEvaluationPositionSchema,
+    message: Type.Union([Type.String(), Type.Null()], {
+        description: "Evaluator-authored diagnostic message when one was produced",
+    }),
+}), { additionalProperties: false });
+/** Structural schema for one already-resolved evaluation request. */
+export const RuleEvaluationRequestSchema = ReadonlyObject(Type.Object({
+    program: Type.String({
+        minLength: 1,
+        description: "Already-resolved evaluator program",
+    }),
+    subjectPaths: ReadonlyObject(Type.Array(NonEmptyStringSchema), {
+        minItems: 1,
+        description: "Non-empty caller-resolved absolute subject paths",
+    }),
+}), { additionalProperties: false });
+/** Structural schema for one completed evaluation. */
+export const RuleEvaluationResultSchema = ReadonlyObject(Type.Object({
+    findings: ReadonlyObject(Type.Array(RuleEvaluationFindingSchema), {
+        description: "Findings reported by the evaluator in provider-defined stable order",
+    }),
+}), { additionalProperties: false });
+/** Provider-neutral mechanical failure reasons for one evaluation attempt. */
+export const RuleEvaluationFailureReasonSchema = Type.Union([
+    Type.Literal("InvalidInput"),
+    Type.Literal("SetupFailed"),
+    Type.Literal("ExecutionFailed"),
+    Type.Literal("TimedOut"),
+    Type.Literal("InvalidOutput"),
+], {
+    description: "Mechanical reason an evaluation could not produce a valid result",
+});
+/** Structural schema for one bounded typed evaluation failure. */
+export const RuleEvaluationFailureSchema = ReadonlyObject(Type.Object({
+    _tag: Type.Literal("RuleEvaluationFailure"),
+    reason: RuleEvaluationFailureReasonSchema,
+    detail: Type.String({
+        minLength: 1,
+        maxLength: MAX_RULE_EVALUATION_FAILURE_DETAIL,
+        description: "Bounded operational failure detail",
+    }),
+}), { additionalProperties: false });
+const ruleEvaluationFailureValidator = Schema.Compile(RuleEvaluationFailureSchema);
+/** Checks an unknown value against the complete rule-evaluation failure contract. */
+export function isRuleEvaluationFailure(input) {
+    return ruleEvaluationFailureValidator.Check(input);
+}

package/dist/providers/grit-effect-platform-node/index.d.ts

@@ -0,0 +1,20 @@
+import type { RuleEvaluationResource } from "@habitat-ai/resource-rule-evaluation";
+import { FileSystem, Path } from "effect";
+import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
+import { type Static, Type } from "typebox";
+type ProviderRequirements = FileSystem.FileSystem | Path.Path | ChildProcessSpawner;
+/** Structural schema for Grit provider construction. */
+export declare const GritRuleEvaluationProviderConfigSchema: Type.TObject<{
+    executable: Type.TReadonly<Type.TString>;
+    timeoutMs: Type.TReadonly<Type.TInteger>;
+}>;
+/** Configuration for one Grit-backed rule-evaluation provider. */
+export type GritRuleEvaluationProviderConfig = Static<typeof GritRuleEvaluationProviderConfigSchema>;
+/**
+ * Creates a Grit-backed evaluator over Effect Platform filesystem, path, and
+ * child-process services.
+ */
+export declare function makeGritRuleEvaluationResource(config: GritRuleEvaluationProviderConfig): RuleEvaluationResource<ProviderRequirements>;
+/** Creates a ready Node realization of the Grit rule-evaluation provider. */
+export declare function makeNodeGritRuleEvaluationResource(config: GritRuleEvaluationProviderConfig): RuleEvaluationResource<never>;
+export {};

package/dist/providers/grit-effect-platform-node/index.js

@@ -0,0 +1,244 @@
+import { NodeServices } from "@effect/platform-node";
+import { MAX_RULE_EVALUATION_FAILURE_DETAIL, RuleEvaluationRequestSchema, } from "@habitat-ai/resource-rule-evaluation";
+import { Effect, Schema as EffectSchema, FileSystem, Path, Stream, } from "effect";
+import { ChildProcess } from "effect/unstable/process";
+import { ReadonlyObject, Type } from "typebox";
+import Schema from "typebox/schema";
+import { Value } from "typebox/value";
+const TEMP_CATALOG_PREFIX = "habitat-rule-evaluation-";
+const GRIT_PATTERN_NAME = "habitat_rule_evaluation";
+/** Maximum bytes retained from either native output stream. */
+const MAX_GRIT_OUTPUT_BYTES = 256 * 1_024;
+/** Structural schema for Grit provider construction. */
+export const GritRuleEvaluationProviderConfigSchema = ReadonlyObject(Type.Object({
+    executable: Type.String({
+        minLength: 1,
+        description: "Caller-selected Grit executable",
+    }),
+    timeoutMs: Type.Integer({
+        minimum: 1,
+        description: "Maximum duration of one native Grit check",
+    }),
+}), { additionalProperties: false });
+const GritPositionSchema = Type.Object({
+    line: Type.Integer({ minimum: 1, description: "One-based Grit source line" }),
+    col: Type.Integer({ minimum: 1, description: "One-based Grit source column" }),
+    offset: Type.Integer({ minimum: 0, description: "Grit-native source offset" }),
+}, { additionalProperties: false, description: "Grit-reported source position" });
+const GritResultSchema = Type.Object({
+    check_id: Type.String({
+        pattern: `^#${GRIT_PATTERN_NAME}/.+$`,
+        description: "Provider-owned Grit check identity with evaluator suffix",
+    }),
+    local_name: Type.Literal(GRIT_PATTERN_NAME, {
+        description: "Provider-owned local Grit pattern name",
+    }),
+    path: Type.String({ minLength: 1, description: "Grit-reported subject path" }),
+    start: GritPositionSchema,
+    end: GritPositionSchema,
+    extra: Type.Object({
+        message: Type.Union([Type.String(), Type.Null()], {
+            description: "Optional Grit diagnostic message",
+        }),
+        severity: Type.Literal("error", {
+            description: "Mechanical severity emitted by the scoped catalog",
+        }),
+    }, { additionalProperties: false, description: "Additional Grit finding data" }),
+}, { additionalProperties: false });
+const GritReportSchema = Type.Object({
+    paths: Type.Array(Type.String({ minLength: 1 }), {
+        description: "Subject paths included in the Grit report",
+    }),
+    results: Type.Array(GritResultSchema, {
+        description: "Findings included in the Grit report",
+    }),
+}, { additionalProperties: false });
+const requestValidator = Schema.Compile(RuleEvaluationRequestSchema);
+const configValidator = Schema.Compile(GritRuleEvaluationProviderConfigSchema);
+/**
+ * Creates a Grit-backed evaluator over Effect Platform filesystem, path, and
+ * child-process services.
+ */
+export function makeGritRuleEvaluationResource(config) {
+    const evaluate = Effect.fn("ruleEvaluation.grit.evaluate")(function* (input) {
+        if (!configValidator.Check(config)) {
+            return yield* fail("InvalidInput", "Grit provider configuration does not match its structural contract");
+        }
+        if (!requestValidator.Check(input)) {
+            return yield* fail("InvalidInput", "Rule-evaluation request requires one resolved program and non-empty subject paths");
+        }
+        const path = yield* Path.Path;
+        if (input.subjectPaths.some((subjectPath) => !path.isAbsolute(subjectPath))) {
+            return yield* fail("InvalidInput", "Rule-evaluation subject paths must be caller-resolved absolute paths");
+        }
+        return yield* Effect.scoped(withScopedGritCatalog(input.program, (catalog) => runGritCheck(config, catalog, input.subjectPaths)));
+    });
+    return Object.freeze({ evaluate });
+}
+/** Creates a ready Node realization of the Grit rule-evaluation provider. */
+export function makeNodeGritRuleEvaluationResource(config) {
+    const resource = makeGritRuleEvaluationResource(config);
+    return Object.freeze({
+        evaluate: (input) => resource.evaluate(input).pipe(Effect.provide(NodeServices.layer)),
+    });
+}
+function withScopedGritCatalog(program, use) {
+    return Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs
+            .makeTempDirectoryScoped({ prefix: TEMP_CATALOG_PREFIX })
+            .pipe(mapPlatform("SetupFailed", "Failed to allocate temporary Grit catalog"));
+        const catalog = Object.freeze({
+            root,
+            gritDirectory: path.join(root, ".grit"),
+            userConfigDirectory: path.join(root, "user-config"),
+            cacheDirectory: path.join(root, "cache"),
+        });
+        yield* fs
+            .makeDirectory(catalog.gritDirectory)
+            .pipe(mapPlatform("SetupFailed", "Failed to create Grit catalog directory"));
+        yield* fs
+            .makeDirectory(catalog.userConfigDirectory)
+            .pipe(mapPlatform("SetupFailed", "Failed to create Grit user-config directory"));
+        yield* fs
+            .makeDirectory(catalog.cacheDirectory)
+            .pipe(mapPlatform("SetupFailed", "Failed to create Grit cache directory"));
+        yield* fs
+            .writeFileString(path.join(catalog.gritDirectory, "grit.yaml"), renderGritCatalog(program))
+            .pipe(mapPlatform("SetupFailed", "Failed to write temporary Grit catalog"));
+        return yield* use(catalog);
+    });
+}
+function runGritCheck(config, catalog, subjectPaths) {
+    const observe = Effect.gen(function* () {
+        const command = ChildProcess.make(config.executable, ["--json", "check", "--no-cache", "--grit-dir", catalog.gritDirectory, ...subjectPaths], {
+            cwd: catalog.root,
+            env: {
+                FORCE_COLOR: undefined,
+                GRIT_CACHE_DIR: catalog.cacheDirectory,
+                GRIT_USER_CONFIG: catalog.userConfigDirectory,
+                GRIT_TELEMETRY_DISABLED: "true",
+                NO_COLOR: undefined,
+            },
+            extendEnv: true,
+            stdin: "ignore",
+            killSignal: "SIGTERM",
+            forceKillAfter: "2 seconds",
+        });
+        const process = yield* command.pipe(mapPlatform("ExecutionFailed", "Failed to start Grit"));
+        const output = yield* Effect.all({
+            stdout: collectBoundedOutput(process.stdout, "stdout"),
+            stderr: collectBoundedOutput(process.stderr, "stderr"),
+            exitCode: process.exitCode.pipe(Effect.map(Number), mapPlatform("ExecutionFailed", "Failed to observe Grit exit")),
+        }, { concurrency: "unbounded" });
+        return Object.freeze(output);
+    }).pipe(Effect.timeoutOrElse({
+        duration: config.timeoutMs,
+        orElse: () => fail("TimedOut", `Grit evaluation exceeded its ${config.timeoutMs}ms timeout`),
+    }));
+    return observe.pipe(Effect.flatMap((observation) => {
+        if (observation.exitCode !== 0) {
+            const detail = observation.stderr.trim() || observation.stdout.trim();
+            return fail("ExecutionFailed", detail.length === 0
+                ? `Grit exited with code ${observation.exitCode}`
+                : `Grit exited with code ${observation.exitCode}: ${detail}`);
+        }
+        if (observation.stdout.trim().length > 0) {
+            return fail("InvalidOutput", "Grit check emitted unexpected stdout alongside its stderr JSON report");
+        }
+        return decodeGritReport(observation.stderr).pipe(Effect.map(resultFromGritReport));
+    }));
+}
+function decodeGritReport(stderr) {
+    if (stderr.trim().length === 0) {
+        return fail("InvalidOutput", "Grit check emitted no stderr JSON report");
+    }
+    return EffectSchema.decodeUnknownEffect(EffectSchema.UnknownFromJsonString)(stderr).pipe(Effect.mapError((error) => failure("InvalidOutput", `Grit check emitted invalid JSON: ${errorMessage(error)}`)), Effect.flatMap((decoded) => Effect.try({
+        try: () => Value.Parse(GritReportSchema, decoded),
+        catch: (error) => failure("InvalidOutput", `Grit check emitted an invalid report: ${errorMessage(error)}`),
+    })));
+}
+function resultFromGritReport(report) {
+    const findings = report.results
+        .map((result) => Object.freeze({
+        path: result.path,
+        start: Object.freeze({
+            line: result.start.line,
+            column: result.start.col,
+            offset: result.start.offset,
+        }),
+        end: Object.freeze({
+            line: result.end.line,
+            column: result.end.col,
+            offset: result.end.offset,
+        }),
+        message: result.extra.message,
+    }))
+        .sort(compareFindings);
+    return Object.freeze({
+        findings: Object.freeze(findings),
+    });
+}
+function renderGritCatalog(program) {
+    return `${JSON.stringify({
+        version: "0.0.2",
+        patterns: [
+            {
+                name: GRIT_PATTERN_NAME,
+                title: GRIT_PATTERN_NAME,
+                level: "error",
+                body: program,
+            },
+        ],
+    }, undefined, 2)}\n`;
+}
+function collectBoundedOutput(stream, channel) {
+    return Stream.runFoldEffect(stream.pipe(Stream.mapError((error) => failure("ExecutionFailed", `Failed to drain Grit ${channel}: ${error.message}`))), () => Object.freeze({ buffer: new Uint8Array(MAX_GRIT_OUTPUT_BYTES), bytes: 0 }), (state, chunk) => {
+        if (chunk.byteLength === 0)
+            return Effect.succeed(state);
+        const bytes = state.bytes + chunk.byteLength;
+        return bytes > MAX_GRIT_OUTPUT_BYTES
+            ? fail("InvalidOutput", `Grit ${channel} exceeded its ${MAX_GRIT_OUTPUT_BYTES}-byte output limit`)
+            : Effect.sync(() => {
+                state.buffer.set(chunk, state.bytes);
+                return Object.freeze({ buffer: state.buffer, bytes });
+            });
+    }).pipe(Effect.flatMap((state) => Effect.try({
+        try: () => new TextDecoder("utf-8", { fatal: true }).decode(state.buffer.subarray(0, state.bytes)),
+        catch: (error) => failure("InvalidOutput", `Grit ${channel} was not valid UTF-8: ${errorMessage(error)}`),
+    })));
+}
+function mapPlatform(reason, context) {
+    return (effect) => effect.pipe(Effect.mapError((error) => failure(reason, `${context}: ${error.message}`)));
+}
+function fail(reason, detail) {
+    return Effect.fail(failure(reason, detail));
+}
+function failure(reason, detail) {
+    const normalized = detail.trim() || "Rule evaluation failed";
+    const bounded = normalized.length <= MAX_RULE_EVALUATION_FAILURE_DETAIL
+        ? normalized
+        : `${normalized.slice(0, MAX_RULE_EVALUATION_FAILURE_DETAIL - 3)}...`;
+    return Object.freeze({
+        _tag: "RuleEvaluationFailure",
+        reason,
+        detail: bounded,
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function compareFindings(left, right) {
+    return (compareText(left.path, right.path) ||
+        left.start.line - right.start.line ||
+        left.start.column - right.start.column ||
+        left.start.offset - right.start.offset ||
+        left.end.line - right.end.line ||
+        left.end.column - right.end.column ||
+        left.end.offset - right.end.offset ||
+        compareText(left.message ?? "", right.message ?? ""));
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@habitat-ai/resource-rule-evaluation",
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/contract.js",
+  "types": "./dist/contract.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    },
+    "./providers/grit-effect-platform-node": {
+      "types": "./dist/providers/grit-effect-platform-node/index.d.ts",
+      "default": "./dist/providers/grit-effect-platform-node/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "bun test test/contract.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.0-beta.101",
+    "effect": "4.0.0-beta.101",
+    "typebox": "1.3.8"
+  },
+  "devDependencies": {
+    "@getgrit/cli": "0.1.0-alpha.1743007075",
+    "typescript": "^5.9.3"
+  },
+  "nx": {
+    "tags": [
+      "type:resource",
+      "layer:resource-contract",
+      "resource:rule-evaluation"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}