@interf/compiler 0.5.1 → 0.6.3

package/dist/packages/project-model/interf-scaffold.js

@@ -0,0 +1,124 @@
+import { mkdirSync, existsSync, writeFileSync, } from "node:fs";
+import { basename, join, relative, sep } from "node:path";
+import { getCompiledWorkflow } from "../workflow-package/workflow-definitions.js";
+import { initializeCompiledRuntimeState, } from "../compiler/state.js";
+import { assertCompiledContainer, assertWritableTargetDir, assertCompiledName, } from "./interf-detect.js";
+import { refreshCompiledBootstrapGuidance } from "./interf-bootstrap.js";
+import { seedCompiledWorkflowPackage } from "../workflow-package/interf-workflow-package.js";
+import { compiledCompiledPathForDataset } from "./project-paths.js";
+import { syncCompiledRawSnapshot } from "./compiled-raw.js";
+import { ensureCompiledZoneTargets, readCompiledSchemaFile } from "../compiler/compiled-schema.js";
+import { findSourceDatasetConfig, listSourceDatasetConfigs, loadSourceFolderConfig, resolveSourceDatasetPath, saveCompiledInterfConfig, } from "./source-config.js";
+import { defaultControlPathForCompiled, workflowPackagePathForCompiled } from "./compiled-paths.js";
+const DEFAULT_INTERFIGNORE = [
+    ".claude/",
+    ".codex/",
+    ".agents/",
+    ".cursor/",
+    ".interf/tests/",
+    ".interf/tests/targets/sandboxes/",
+    ".interf/runtime/",
+    "",
+].join("\n");
+const UNCOMPILED_COMPILED_PLACEHOLDER = "Not yet compiled. Run `interf compile` to build this context folder.";
+function renderUncompiledCompiledFile(compiledName, relativePath, about) {
+    return [
+        `# ${compiledName} — ${relativePath}`,
+        "",
+        UNCOMPILED_COMPILED_PLACEHOLDER,
+        ...(about ? ["", `About: ${about}`] : []),
+        "",
+    ].join("\n");
+}
+function compiledGitignoreEntries(compiledPath) {
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
+    const zoneEntries = (schema?.zones ?? [])
+        .filter((zone) => zone.kind !== "runtime")
+        .map((zone) => zone.kind === "file" ? zone.path : `${zone.path}/`);
+    return [
+        ...zoneEntries,
+        ".claude/",
+        ".codex/",
+        ".agents/",
+        ".cursor/",
+        ".interf/tests/",
+        ".interf/tests/targets/sandboxes/",
+        ".interf/runtime/",
+    ];
+}
+function scaffoldCompiledOutputs(compiledPath, compiledName, about) {
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(compiledPath));
+    if (!schema) {
+        throw new Error(`Missing workflow schema at ${workflowPackagePathForCompiled(compiledPath)}.`);
+    }
+    ensureCompiledZoneTargets(compiledPath, schema);
+    for (const zone of schema.zones) {
+        if (!zone.required || zone.kind !== "file" || zone.role !== "output")
+            continue;
+        const targetPath = join(compiledPath, zone.path);
+        if (existsSync(targetPath))
+            continue;
+        writeFileSync(targetPath, renderUncompiledCompiledFile(compiledName, zone.path, about));
+    }
+}
+export function createCompiled(name, sourcePath, workflowId = "interf", about, datasetPath) {
+    assertCompiledName(name, "Context folder");
+    assertCompiledContainer(sourcePath);
+    const compiledPath = compiledCompiledPathForDataset(sourcePath, name);
+    assertWritableTargetDir(compiledPath, "Context folder");
+    mkdirSync(compiledPath, { recursive: true });
+    const savedCompiled = findSourceDatasetConfig(loadSourceFolderConfig(sourcePath), name);
+    const selectedWorkflow = getCompiledWorkflow(workflowId, { sourcePath });
+    const resolvedAbout = about ?? savedCompiled?.about;
+    const resolvedDatasetPath = (() => {
+        if (savedCompiled) {
+            return resolveSourceDatasetPath(sourcePath, savedCompiled);
+        }
+        if (datasetPath) {
+            return datasetPath;
+        }
+        const configuredDatasets = listSourceDatasetConfigs(loadSourceFolderConfig(sourcePath));
+        if (configuredDatasets.length === 1) {
+            return resolveSourceDatasetPath(sourcePath, configuredDatasets[0]);
+        }
+        throw new Error("Cannot infer the source folder for this context folder. Select a source folder first or pass an explicit dataset path.");
+    })();
+    saveCompiledInterfConfig(compiledPath, {
+        type: "compiled",
+        name,
+        ...(resolvedAbout ? { about: resolvedAbout } : {}),
+        workflow: selectedWorkflow.id,
+        ...(typeof savedCompiled?.max_attempts === "number"
+            ? { max_attempts: savedCompiled.max_attempts }
+            : {}),
+        ...(typeof savedCompiled?.max_loops === "number"
+            ? { max_loops: savedCompiled.max_loops }
+            : {}),
+        checks: savedCompiled?.checks ?? [],
+        workflow_origin: {
+            selected: selectedWorkflow.id,
+            local_draft: false,
+        },
+        source: {
+            path: "./raw",
+            control_path: defaultControlPathForCompiled(compiledPath),
+            dataset_path: relative(compiledPath, resolvedDatasetPath).split(sep).join("/") || ".",
+        },
+    });
+    mkdirSync(join(compiledPath, "raw"), { recursive: true });
+    syncCompiledRawSnapshot(compiledPath, resolvedDatasetPath);
+    writeFileSync(join(compiledPath, ".interfignore"), DEFAULT_INTERFIGNORE);
+    seedCompiledWorkflowPackage({
+        compiledPath,
+        sourcePath,
+        workflowId: selectedWorkflow.id,
+    });
+    scaffoldCompiledOutputs(compiledPath, name, about);
+    refreshCompiledBootstrapGuidance(compiledPath);
+    writeFileSync(join(compiledPath, ".gitignore"), [...compiledGitignoreEntries(compiledPath), ""].join("\n"));
+    initializeCompiledRuntimeState(compiledPath);
+    return compiledPath;
+}
+export function defaultCompiledNameForSource(sourcePath) {
+    return basename(sourcePath);
+}

package/dist/packages/project-model/interf.d.ts

@@ -0,0 +1,5 @@
+export { INTERF_CONTAINER_NAME, WORKFLOW_CONTAINER_NAME, TEST_CONTAINER_NAME, INTERF_CONFIG_FILE, WORKFLOW_PACKAGE_DIR, readInterfConfig, detectInterf, resolveCompiled, resolveSourceFolderPath, resolveSourceControlPath, resolveSourceInputPath, listCompiledDatasetsForSourceFolder, hasSourceFolderInput, assertCompiledContainer, assertWritableTargetDir, assertCompiledName, } from "./interf-detect.js";
+export type { InterfConfig, ResolvedCompiled } from "./interf-detect.js";
+export { ensureCompiledRawBinding, resolveCompiledRawPath, syncCompiledRawSnapshot, } from "./compiled-raw.js";
+export { refreshCompiledBootstrapGuidance, renderClaudeBootstrap, } from "./interf-bootstrap.js";
+export { createCompiled, defaultCompiledNameForSource, } from "./interf-scaffold.js";

package/dist/packages/project-model/interf.js

@@ -0,0 +1,4 @@
+export { INTERF_CONTAINER_NAME, WORKFLOW_CONTAINER_NAME, TEST_CONTAINER_NAME, INTERF_CONFIG_FILE, WORKFLOW_PACKAGE_DIR, readInterfConfig, detectInterf, resolveCompiled, resolveSourceFolderPath, resolveSourceControlPath, resolveSourceInputPath, listCompiledDatasetsForSourceFolder, hasSourceFolderInput, assertCompiledContainer, assertWritableTargetDir, assertCompiledName, } from "./interf-detect.js";
+export { ensureCompiledRawBinding, resolveCompiledRawPath, syncCompiledRawSnapshot, } from "./compiled-raw.js";
+export { refreshCompiledBootstrapGuidance, renderClaudeBootstrap, } from "./interf-bootstrap.js";
+export { createCompiled, defaultCompiledNameForSource, } from "./interf-scaffold.js";

package/dist/packages/project-model/lib/schema.d.ts

@@ -0,0 +1,125 @@
+import { z } from "zod";
+export declare const DatasetNameSchema: z.ZodString;
+export declare const SourceTruthCheckSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    question: z.ZodString;
+    answer: z.ZodOptional<z.ZodString>;
+    expect: z.ZodOptional<z.ZodObject<{
+        must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        must_include_one_of: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+        must_not_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        min_words: z.ZodOptional<z.ZodNumber>;
+        max_words: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    strictness: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const SourceDatasetConfigSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    path: z.ZodString;
+    about: z.ZodOptional<z.ZodString>;
+    workflow: z.ZodOptional<z.ZodString>;
+    max_attempts: z.ZodOptional<z.ZodNumber>;
+    max_loops: z.ZodOptional<z.ZodNumber>;
+    checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        question: z.ZodString;
+        answer: z.ZodOptional<z.ZodString>;
+        expect: z.ZodOptional<z.ZodObject<{
+            must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            must_include_one_of: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+            must_not_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            min_words: z.ZodOptional<z.ZodNumber>;
+            max_words: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        strictness: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const CompiledInterfConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"compiled">;
+    name: z.ZodString;
+    about: z.ZodOptional<z.ZodString>;
+    workflow: z.ZodString;
+    max_attempts: z.ZodOptional<z.ZodNumber>;
+    max_loops: z.ZodOptional<z.ZodNumber>;
+    checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        question: z.ZodString;
+        answer: z.ZodOptional<z.ZodString>;
+        expect: z.ZodOptional<z.ZodObject<{
+            must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            must_include_one_of: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+            must_not_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            min_words: z.ZodOptional<z.ZodNumber>;
+            max_words: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        strictness: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    workflow_origin: z.ZodOptional<z.ZodObject<{
+        selected: z.ZodString;
+        local_draft: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    source: z.ZodObject<{
+        path: z.ZodString;
+        control_path: z.ZodOptional<z.ZodString>;
+        dataset_path: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$loose>;
+export declare const InterfConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"compiled">;
+    name: z.ZodString;
+    about: z.ZodOptional<z.ZodString>;
+    workflow: z.ZodString;
+    max_attempts: z.ZodOptional<z.ZodNumber>;
+    max_loops: z.ZodOptional<z.ZodNumber>;
+    checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        question: z.ZodString;
+        answer: z.ZodOptional<z.ZodString>;
+        expect: z.ZodOptional<z.ZodObject<{
+            must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            must_include_one_of: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+            must_not_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            min_words: z.ZodOptional<z.ZodNumber>;
+            max_words: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        strictness: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    workflow_origin: z.ZodOptional<z.ZodObject<{
+        selected: z.ZodString;
+        local_draft: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    source: z.ZodObject<{
+        path: z.ZodString;
+        control_path: z.ZodOptional<z.ZodString>;
+        dataset_path: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$loose>;
+export declare const SourceFolderConfigSchema: z.ZodObject<{
+    datasets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        path: z.ZodString;
+        about: z.ZodOptional<z.ZodString>;
+        workflow: z.ZodOptional<z.ZodString>;
+        max_attempts: z.ZodOptional<z.ZodNumber>;
+        max_loops: z.ZodOptional<z.ZodNumber>;
+        checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            question: z.ZodString;
+            answer: z.ZodOptional<z.ZodString>;
+            expect: z.ZodOptional<z.ZodObject<{
+                must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                must_include_one_of: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+                must_not_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                min_words: z.ZodOptional<z.ZodNumber>;
+                max_words: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            strictness: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type SourceTruthCheck = z.infer<typeof SourceTruthCheckSchema>;
+export type SourceDatasetConfig = z.infer<typeof SourceDatasetConfigSchema>;
+export type InterfConfig = z.infer<typeof InterfConfigSchema>;
+export type SourceFolderConfig = z.infer<typeof SourceFolderConfigSchema>;

package/dist/packages/project-model/lib/schema.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { SourceCompiledMaxAttemptsSchema, SourceCompiledMaxLoopsSchema, TestCaseExpectSchema, WorkflowIdPattern, WorkflowIdSchema, } from "../../compiler/lib/schema.js";
+const DatasetNamePattern = /^[a-z0-9][a-z0-9-]*$/;
+const RESERVED_DATASET_NAMES = new Set(["tests", "workflows"]);
+export const DatasetNameSchema = z
+    .string()
+    .regex(DatasetNamePattern, "Dataset names must use lowercase letters, numbers, and dashes only.")
+    .refine((value) => !RESERVED_DATASET_NAMES.has(value), "Dataset name is reserved.");
+export const SourceTruthCheckSchema = z.object({
+    id: z.string().regex(WorkflowIdPattern).optional(),
+    question: z.string().min(1),
+    answer: z.string().min(1).optional(),
+    expect: TestCaseExpectSchema.optional(),
+    strictness: z.string().min(1).optional(),
+}).strict().superRefine((value, ctx) => {
+    if (!value.answer && !value.expect) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["answer"],
+            message: "Truth checks need `answer` or `expect`.",
+        });
+    }
+});
+export const SourceDatasetConfigSchema = z.object({
+    id: z.string().regex(WorkflowIdPattern).optional(),
+    name: DatasetNameSchema,
+    path: z.string().min(1),
+    about: z.string().min(1).optional(),
+    workflow: WorkflowIdSchema.optional(),
+    max_attempts: SourceCompiledMaxAttemptsSchema.optional(),
+    max_loops: SourceCompiledMaxLoopsSchema.optional(),
+    checks: z.array(SourceTruthCheckSchema).default([]),
+}).strict();
+export const CompiledInterfConfigSchema = z.object({
+    type: z.literal("compiled"),
+    name: DatasetNameSchema,
+    about: z.string().optional(),
+    workflow: WorkflowIdSchema,
+    max_attempts: SourceCompiledMaxAttemptsSchema.optional(),
+    max_loops: SourceCompiledMaxLoopsSchema.optional(),
+    checks: z.array(SourceTruthCheckSchema).default([]),
+    workflow_origin: z.object({
+        selected: WorkflowIdSchema,
+        local_draft: z.boolean().optional(),
+    }).optional(),
+    source: z.object({
+        path: z.string(),
+        control_path: z.string().optional(),
+        dataset_path: z.string(),
+    }),
+}).passthrough();
+export const InterfConfigSchema = CompiledInterfConfigSchema;
+export const SourceFolderConfigSchema = z.object({
+    datasets: z.array(SourceDatasetConfigSchema).optional(),
+}).strict().superRefine((value, ctx) => {
+    if ((value.datasets?.length ?? 0) === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Interf project config needs at least one dataset.",
+        });
+    }
+});

package/dist/packages/project-model/project-paths.d.ts

@@ -0,0 +1,11 @@
+export declare const PROJECT_INTERF_DIR = "interf";
+export declare const PROJECT_TESTS_DIR = "tests";
+export declare function projectInterfRoot(projectPath: string): string;
+export declare function compiledCompiledPathForDataset(projectPath: string, datasetName: string): string;
+export declare function datasetTestsRoot(projectPath: string, datasetName: string): string;
+export type DatasetTestTargetLabel = "file-as-is" | "compiled";
+export declare function datasetTestRunsRoot(projectPath: string, datasetName: string, target: DatasetTestTargetLabel): string;
+export declare function datasetLatestTestStatePath(projectPath: string, datasetName: string): string;
+export declare function datasetLatestTestSummaryPath(projectPath: string, datasetName: string): string;
+export declare function normalizeDatasetTestRunId(input: string): string;
+export declare function datasetTestRunPath(projectPath: string, datasetName: string, target: DatasetTestTargetLabel, generatedAt: string, runId: string, runSuffix?: string | null): string;

package/dist/packages/project-model/project-paths.js

@@ -0,0 +1,32 @@
+import { join } from "node:path";
+export const PROJECT_INTERF_DIR = "interf";
+export const PROJECT_TESTS_DIR = "tests";
+export function projectInterfRoot(projectPath) {
+    return join(projectPath, PROJECT_INTERF_DIR);
+}
+export function compiledCompiledPathForDataset(projectPath, datasetName) {
+    return join(projectInterfRoot(projectPath), datasetName);
+}
+export function datasetTestsRoot(projectPath, datasetName) {
+    return join(projectInterfRoot(projectPath), PROJECT_TESTS_DIR, datasetName);
+}
+export function datasetTestRunsRoot(projectPath, datasetName, target) {
+    return join(datasetTestsRoot(projectPath, datasetName), target, "runs");
+}
+export function datasetLatestTestStatePath(projectPath, datasetName) {
+    return join(datasetTestsRoot(projectPath, datasetName), "latest.json");
+}
+export function datasetLatestTestSummaryPath(projectPath, datasetName) {
+    return join(datasetTestsRoot(projectPath, datasetName), "latest.md");
+}
+export function normalizeDatasetTestRunId(input) {
+    return input
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+export function datasetTestRunPath(projectPath, datasetName, target, generatedAt, runId, runSuffix) {
+    return join(datasetTestRunsRoot(projectPath, datasetName, target), `${generatedAt.replace(/[:.]/g, "-")}-${runId}${runSuffix ? `-${normalizeDatasetTestRunId(runSuffix)}` : ""}.json`);
+}

package/dist/packages/project-model/source-config.d.ts

@@ -0,0 +1,38 @@
+import { type InterfConfig, type SourceTruthCheck, type SourceDatasetConfig, type SourceFolderConfig } from "./lib/schema.js";
+import type { TestSpec, TestTargetType } from "../testing/lib/schema.js";
+export declare const SOURCE_FOLDER_CONFIG_FILE = "interf.json";
+export interface LoadedSourceTestSpec extends TestSpec {
+    id: string;
+    filePath: string;
+}
+export declare function fingerprintTruthChecks(checks: SourceTruthCheck[]): string;
+export declare function loadSourceFolderConfig(sourcePath: string): SourceFolderConfig | null;
+export interface WritableSourceProjectConfig {
+    datasets?: SourceDatasetConfig[];
+}
+export declare function listSourceDatasetConfigs(config: SourceFolderConfig | null): SourceDatasetConfig[];
+export declare function resolveDatasetCompileMaxAttempts(datasetConfig: Pick<SourceDatasetConfig, "max_attempts">, override?: number | null): number | null;
+export declare function resolveDatasetCompileMaxLoops(datasetConfig: Pick<SourceDatasetConfig, "max_loops">, override?: number | null): number | null;
+export declare function getDefaultSourceDatasetConfig(config: SourceFolderConfig | null): SourceDatasetConfig | null;
+export declare function findSourceDatasetConfig(config: SourceFolderConfig | null, datasetName: string): SourceDatasetConfig | null;
+export declare function saveSourceFolderConfig(sourcePath: string, config: WritableSourceProjectConfig): void;
+export declare function appendSourceDatasetChecks(sourcePath: string, datasetName: string, checks: SourceTruthCheck[]): void;
+export declare function upsertSourceDatasetConfig(sourcePath: string, datasetConfig: SourceDatasetConfig, options?: {
+    matchName?: string;
+}): void;
+export declare function compiledMaxAttempts(maxAttempts: number | null | undefined): number | undefined;
+export declare function compiledMaxLoops(maxLoops: number | null | undefined): number | undefined;
+export declare function sourceDatasetConfigFromInterfConfig(config: InterfConfig, datasetPath?: string): SourceDatasetConfig;
+export declare function loadCompiledDatasetConfig(compiledPath: string): SourceDatasetConfig | null;
+export declare function saveCompiledInterfConfig(compiledPath: string, config: InterfConfig): InterfConfig;
+export declare function syncCompiledInterfConfigFromSourceDatasetConfig(compiledPath: string, datasetConfig: SourceDatasetConfig): InterfConfig;
+export declare function buildTestSpecFromSourceFolderConfig(options: {
+    sourcePath: string;
+    targetName?: string | null;
+    targetType?: TestTargetType;
+}): LoadedSourceTestSpec | null;
+export declare function buildTestSpecFromCompiledDatasetConfig(options: {
+    compiledPath: string;
+    targetType?: TestTargetType;
+}): LoadedSourceTestSpec | null;
+export declare function resolveSourceDatasetPath(projectPath: string, datasetConfig: Pick<SourceDatasetConfig, "path">): string;