@interf/compiler 0.4.0 → 0.5.0

package/dist/lib/local-workflows.js

@@ -6,9 +6,9 @@ import { isMarkdownFile } from "./util.js";
 import { listFilesRecursive } from "./filesystem.js";
 import { warnInterf } from "./logger.js";
 import { readJsonFileUnchecked, readJsonFileWithSchema } from "./parse.js";
-import { listBuiltinWorkspaceZoneSpecs, validateWorkspaceContractSequence, } from "./workflow-abi.js";
-import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowStageZoneAccessSchema, WorkflowWorkspaceSchemaSchema, WorkflowIdPattern, } from "./schema.js";
-import { writeWorkspaceSchemaFile, workspaceSchemaFilePath } from "./workspace-schema.js";
+import { listBuiltinCompiledZoneSpecs, } from "./workflow-abi.js";
+import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowStageZoneAccessSchema, WorkflowCompiledSchemaSchema, WorkflowIdPattern, } from "./schema.js";
+import { writeCompiledSchemaFile, compiledSchemaFilePath } from "./compiled-schema.js";
 const LocalWorkflowStageDefinitionSchema = z.object({
     id: z.string().regex(WorkflowIdPattern),
     label: z.string().min(1),
@@ -21,32 +21,13 @@ const LocalWorkflowStageDefinitionSchema = z.object({
 });
 const LocalWorkflowDefinitionSchema = z.object({
     id: z.string().regex(WorkflowIdPattern),
-    type: z.literal("workspace"),
+    type: z.literal("compiled"),
     compiler_api: WorkflowCompilerApiSchema.optional(),
     label: z.string().min(1),
     hint: z.string().min(1),
     extends: z.string().regex(WorkflowIdPattern).optional(),
     stages: z.array(LocalWorkflowStageDefinitionSchema).min(1).optional(),
     stage_policy_notes: z.record(z.string(), z.array(z.string())).optional(),
-}).superRefine((value, ctx) => {
-    const stages = value.stages ?? [];
-    if (stages.length === 0)
-        return;
-    const sequence = validateWorkspaceContractSequence(stages.map((stage) => stage.contract_type));
-    if (!sequence.orderValid) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["stages"],
-            message: "Workspace workflow stages must keep non-decreasing order: file-evidence -> knowledge-structure -> query-shape.",
-        });
-    }
-    for (const missing of sequence.missing) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ["stages"],
-            message: `Workspace workflows must include at least one ${missing} stage.`,
-        });
-    }
 });
 function workflowRootPath(sourcePath) {
     return join(sourcePath, "interf", "workflows");
@@ -75,21 +56,21 @@ export function loadWorkflowDefinitionFromDir(dirPath) {
     const definition = readJsonFileWithSchema(workflowPath, "local workflow definition", LocalWorkflowDefinitionSchema);
     if (!definition)
         return null;
-    const schemaPath = workspaceSchemaFilePath(dirPath);
-    const workspaceSchema = readJsonFileWithSchema(schemaPath, "workspace schema", WorkflowWorkspaceSchemaSchema);
-    if (!workspaceSchema)
+    const schemaPath = compiledSchemaFilePath(dirPath);
+    const compiledSchema = readJsonFileWithSchema(schemaPath, "compiled schema", WorkflowCompiledSchemaSchema);
+    if (!compiledSchema)
         return null;
-    if (definition.type !== "workspace") {
+    if (definition.type !== "compiled") {
         warnInterf(`Warning: local workflow definition at ${workflowPath} has unexpected type "${definition.type}".`);
         return null;
     }
     return {
         ...definition,
-        workspace_schema: workspaceSchema,
+        compiled_schema: compiledSchema,
         starter_docs: collectStarterDocs(dirPath),
         directoryPath: dirPath,
         workflowPath,
-        workspaceSchemaPath: schemaPath,
+        compiledSchemaPath: schemaPath,
     };
 }
 export function listLocalWorkflowDefinitions(sourcePath) {
@@ -167,7 +148,7 @@ function readWorkflowJsonObject(dirPath) {
 }
 export function patchWorkflowPackageMetadata(dirPath, options = {}) {
     const workflowPath = join(dirPath, "workflow.json");
-    const schemaPath = workspaceSchemaFilePath(dirPath);
+    const schemaPath = compiledSchemaFilePath(dirPath);
     const workflowJson = readWorkflowJsonObject(dirPath);
     const normalizedStages = Array.isArray(workflowJson.stages) && workflowJson.stages.length > 0
         ? workflowJson.stages
@@ -177,9 +158,9 @@ export function patchWorkflowPackageMetadata(dirPath, options = {}) {
     }
     const nextWorkflowJson = {
         ...workflowJson,
-        type: "workspace",
+        type: "compiled",
         compiler_api: workflowJson.compiler_api ?? {
-            kind: "workspace",
+            kind: "compiled",
             version: 1,
         },
         stages: normalizedStages,
@@ -196,12 +177,12 @@ export function patchWorkflowPackageMetadata(dirPath, options = {}) {
         delete nextWorkflowJson.stage_policy_notes;
     }
     writeFileSync(workflowPath, JSON.stringify(nextWorkflowJson, null, 2) + "\n");
-    const schemaLabel = `${String(nextWorkflowJson.label ?? workflowJson.label ?? options.id ?? "Workflow")} workspace schema`;
+    const schemaLabel = `${String(nextWorkflowJson.label ?? workflowJson.label ?? options.id ?? "Workflow")} compiled schema`;
     if (!existsSync(schemaPath)) {
-        writeWorkspaceSchemaFile(dirPath, normalizedStages, schemaLabel);
+        writeCompiledSchemaFile(dirPath, normalizedStages, schemaLabel);
         return;
     }
-    const rawSchema = readJsonFileUnchecked(schemaPath, "workspace schema");
+    const rawSchema = readJsonFileUnchecked(schemaPath, "compiled schema");
     if (!rawSchema || typeof rawSchema !== "object" || Array.isArray(rawSchema))
         return;
     writeFileSync(schemaPath, JSON.stringify({
@@ -212,11 +193,11 @@ export function patchWorkflowPackageMetadata(dirPath, options = {}) {
 export function describeWorkflowPackagePortability(dirPath) {
     const issues = [];
     const workflowPath = join(dirPath, "workflow.json");
-    const schemaPath = workspaceSchemaFilePath(dirPath);
+    const schemaPath = compiledSchemaFilePath(dirPath);
     if (!existsSync(workflowPath))
         issues.push("missing workflow.json");
     if (!existsSync(schemaPath))
-        issues.push("missing workspace.schema.json");
+        issues.push("missing compiled.schema.json");
     if (!existsSync(join(dirPath, "README.md")))
         issues.push("missing README.md");
     if (!existsSync(join(dirPath, "improve", "SKILL.md")))
@@ -271,7 +252,7 @@ export function copyWorkflowPackageDirectory(sourceWorkflowPath, targetWorkflowP
 }
 export function validateWorkflowPackage(dirPath) {
     const workflowPath = join(dirPath, "workflow.json");
-    const schemaPath = workspaceSchemaFilePath(dirPath);
+    const schemaPath = compiledSchemaFilePath(dirPath);
     if (!existsSync(workflowPath)) {
         return {
             ok: false,
@@ -308,7 +289,7 @@ export function validateWorkflowPackage(dirPath) {
         errors.push("workflow.json must declare explicit stages. Legacy inherited packages are not portable.");
     }
     if (!existsSync(schemaPath)) {
-        errors.push("Missing workspace.schema.json.");
+        errors.push("Missing compiled.schema.json.");
     }
     if (!existsSync(join(dirPath, "README.md"))) {
         errors.push("Missing README.md.");
@@ -319,24 +300,11 @@ export function validateWorkflowPackage(dirPath) {
     if (!existsSync(join(dirPath, "use", "query", "SKILL.md"))) {
         errors.push("Missing use/query/SKILL.md.");
     }
-    const workspaceSchema = readJsonFileWithSchema(schemaPath, "workspace schema", WorkflowWorkspaceSchemaSchema);
-    if (!workspaceSchema) {
-        errors.push("workspace.schema.json is missing or invalid.");
+    const compiledSchema = readJsonFileWithSchema(schemaPath, "compiled schema", WorkflowCompiledSchemaSchema);
+    if (!compiledSchema) {
+        errors.push("compiled.schema.json is missing or invalid.");
     }
     if (def.stages && def.stages.length > 0) {
-        const contractTypes = def.stages.map((stage) => stage.contract_type);
-        const sequence = validateWorkspaceContractSequence(contractTypes);
-        if (def.stages.length < 3) {
-            errors.push("Workspace workflows must include summarize, structure, and shape stages in order.");
-        }
-        else if (!sequence.orderValid) {
-            errors.push("Workspace workflow stages must keep non-decreasing order: file-evidence -> knowledge-structure -> query-shape.");
-        }
-        else {
-            for (const missing of sequence.missing) {
-                errors.push(`Workspace workflows must include at least one ${missing} stage.`);
-            }
-        }
         for (const stage of def.stages) {
             const skillDir = typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
                 ? stage.skill_dir
@@ -346,12 +314,12 @@ export function validateWorkflowPackage(dirPath) {
             }
         }
     }
-    if (workspaceSchema) {
+    if (compiledSchema) {
         const stages = def.stages ?? [];
         const stageIds = new Set(stages.map((stage) => stage.id));
         const seenPaths = new Map();
         const seenZoneIds = new Set();
-        const zoneById = new Map(workspaceSchema.zones.map((zone) => [zone.id, zone]));
+        const zoneById = new Map(compiledSchema.zones.map((zone) => [zone.id, zone]));
         const normalizedParts = (value) => value.replaceAll("\\", "/").split("/").filter(Boolean);
         const hasOverlappingPath = (value, other) => {
             const a = normalizedParts(value);
@@ -360,26 +328,26 @@ export function validateWorkflowPackage(dirPath) {
             const longer = a.length <= b.length ? b : a;
             return shorter.every((part, index) => longer[index] === part);
         };
-        for (const zone of workspaceSchema.zones) {
+        for (const zone of compiledSchema.zones) {
             if (seenZoneIds.has(zone.id)) {
-                errors.push(`workspace.schema.json repeats zone id "${zone.id}".`);
+                errors.push(`compiled.schema.json repeats zone id "${zone.id}".`);
             }
             seenZoneIds.add(zone.id);
             const existingPathOwner = seenPaths.get(zone.path);
             if (existingPathOwner) {
-                errors.push(`workspace.schema.json repeats zone path "${zone.path}".`);
+                errors.push(`compiled.schema.json repeats zone path "${zone.path}".`);
             }
             for (const [existingPath, existingZoneId] of seenPaths.entries()) {
                 if (existingPath === zone.path)
                     continue;
                 if (hasOverlappingPath(zone.path, existingPath)) {
-                    errors.push(`workspace.schema.json zones "${zone.id}" and "${existingZoneId}" overlap on path "${zone.path}" / "${existingPath}".`);
+                    errors.push(`compiled.schema.json zones "${zone.id}" and "${existingZoneId}" overlap on path "${zone.path}" / "${existingPath}".`);
                 }
             }
             seenPaths.set(zone.path, zone.id);
             for (const owner of zone.owned_by) {
                 if (!stageIds.has(owner)) {
-                    errors.push(`workspace.schema.json references unknown stage "${owner}" for zone "${zone.path}".`);
+                    errors.push(`compiled.schema.json references unknown stage "${owner}" for zone "${zone.path}".`);
                 }
             }
         }
@@ -396,21 +364,18 @@ export function validateWorkflowPackage(dirPath) {
                     continue;
                 }
                 if (!zone.owned_by.includes(stage.id)) {
-                    errors.push(`Stage "${stage.id}" writes zone "${zoneId}" but that zone is not owned by the stage in workspace.schema.json.`);
+                    errors.push(`Stage "${stage.id}" writes zone "${zoneId}" but that zone is not owned by the stage in compiled.schema.json.`);
                 }
             }
         }
-        for (const requiredZone of listBuiltinWorkspaceZoneSpecs()) {
+        for (const requiredZone of listBuiltinCompiledZoneSpecs().filter((zone) => zone.id === "raw" || zone.id === "runtime")) {
             const match = zoneById.get(requiredZone.id);
             if (!match) {
-                errors.push(`workspace.schema.json is missing required zone "${requiredZone.id}".`);
+                errors.push(`compiled.schema.json is missing required zone "${requiredZone.id}".`);
                 continue;
             }
-            if (match.path !== requiredZone.path) {
-                errors.push(`workspace.schema.json zone "${requiredZone.id}" should point at "${requiredZone.path}".`);
-            }
             if (match.kind !== requiredZone.kind) {
-                errors.push(`workspace.schema.json zone "${requiredZone.path}" should be kind "${requiredZone.kind}".`);
+                errors.push(`compiled.schema.json zone "${requiredZone.id}" should be kind "${requiredZone.kind}".`);
             }
         }
     }
@@ -420,7 +385,7 @@ export function validateWorkflowPackage(dirPath) {
     const counts = {
         starter_docs: collectStarterDocs(dirPath).length,
         compile_stage_docs: stageDirs.length,
-        workspace_zones: workspaceSchema?.zones.length ?? 0,
+        compiled_zones: compiledSchema?.zones.length ?? 0,
     };
     return {
         ok: errors.length === 0,

package/dist/lib/obsidian.d.ts

@@ -1 +1 @@
-export declare function writeObsidianDefaults(dirPath: string, type: "workspace"): void;
+export declare function writeObsidianDefaults(dirPath: string, type: "compiled"): void;

package/dist/lib/parse.js

@@ -30,6 +30,91 @@ export function renderJsonFrontmatter(frontmatter) {
         "---",
     ].join("\n");
 }
+function parseQuotedString(value) {
+    if (value.length < 2)
+        return null;
+    const quote = value[0];
+    if ((quote !== "\"" && quote !== "'") || value[value.length - 1] !== quote)
+        return null;
+    const inner = value.slice(1, -1);
+    if (quote === "\"") {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    return inner.replace(/\\'/g, "'");
+}
+function parseYamlScalar(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return "";
+    const quoted = parseQuotedString(trimmed);
+    if (quoted !== null)
+        return quoted;
+    if (trimmed === "true")
+        return true;
+    if (trimmed === "false")
+        return false;
+    if (trimmed === "null")
+        return null;
+    if (/^-?\d+(?:\.\d+)?$/.test(trimmed))
+        return Number(trimmed);
+    if ((trimmed.startsWith("[") && trimmed.endsWith("]"))
+        || (trimmed.startsWith("{") && trimmed.endsWith("}"))) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return trimmed;
+        }
+    }
+    return trimmed;
+}
+function parseYamlFrontmatter(frontmatterText) {
+    const lines = frontmatterText.split("\n");
+    const frontmatter = {};
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        const trimmed = line.trim();
+        if (trimmed.length === 0 || trimmed.startsWith("#"))
+            continue;
+        const match = line.match(/^([A-Za-z0-9_-]+):(?:\s+(.*))?$/);
+        if (!match)
+            return null;
+        const [, key, inlineValue] = match;
+        if (!key)
+            return null;
+        if (inlineValue && inlineValue.trim().length > 0) {
+            frontmatter[key] = parseYamlScalar(inlineValue);
+            continue;
+        }
+        const items = [];
+        let cursor = index + 1;
+        while (cursor < lines.length) {
+            const nextLine = lines[cursor] ?? "";
+            const nextTrimmed = nextLine.trim();
+            if (nextTrimmed.length === 0) {
+                cursor += 1;
+                continue;
+            }
+            const itemMatch = nextLine.match(/^\s*-\s+(.*)$/);
+            if (!itemMatch || !/^\s+/.test(nextLine))
+                break;
+            items.push(parseYamlScalar(itemMatch[1] ?? ""));
+            cursor += 1;
+        }
+        if (items.length > 0) {
+            frontmatter[key] = items;
+            index = cursor - 1;
+            continue;
+        }
+        frontmatter[key] = "";
+    }
+    return Object.keys(frontmatter).length > 0 ? frontmatter : null;
+}
 export function parseJsonFrontmatter(content) {
     const normalized = content.replace(/\r\n/g, "\n");
     const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
@@ -49,6 +134,12 @@ export function parseJsonFrontmatter(content) {
         };
     }
     catch {
-        return null;
+        const frontmatter = parseYamlFrontmatter(frontmatterText);
+        if (!frontmatter)
+            return null;
+        return {
+            frontmatter,
+            body,
+        };
     }
 }

package/dist/lib/project-paths.d.ts

@@ -0,0 +1,13 @@
+export declare const PROJECT_INTERF_DIR = "interf";
+export declare const PROJECT_WORKFLOW_DIR = "workflows";
+export declare const PROJECT_COMPILED_DIR = "compiled";
+export declare const PROJECT_TESTS_DIR = "tests";
+export declare function projectInterfRoot(projectPath: string): string;
+export declare function projectWorkflowRoot(projectPath: string): string;
+export declare function datasetArtifactRoot(projectPath: string, datasetName: 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;

package/dist/lib/project-paths.js

@@ -0,0 +1,29 @@
+import { join } from "node:path";
+export const PROJECT_INTERF_DIR = "interf";
+export const PROJECT_WORKFLOW_DIR = "workflows";
+export const PROJECT_COMPILED_DIR = "compiled";
+export const PROJECT_TESTS_DIR = "tests";
+export function projectInterfRoot(projectPath) {
+    return join(projectPath, PROJECT_INTERF_DIR);
+}
+export function projectWorkflowRoot(projectPath) {
+    return join(projectInterfRoot(projectPath), PROJECT_WORKFLOW_DIR);
+}
+export function datasetArtifactRoot(projectPath, datasetName) {
+    return join(projectInterfRoot(projectPath), datasetName);
+}
+export function compiledCompiledPathForDataset(projectPath, datasetName) {
+    return join(datasetArtifactRoot(projectPath, datasetName), PROJECT_COMPILED_DIR);
+}
+export function datasetTestsRoot(projectPath, datasetName) {
+    return join(datasetArtifactRoot(projectPath, datasetName), PROJECT_TESTS_DIR);
+}
+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");
+}

package/dist/lib/runtime-acceptance.d.ts

@@ -1,3 +1,9 @@
-import { type RuntimeStageContract } from "./schema.js";
+import { type CompiledState, type RuntimeStageAcceptance, type RuntimeStageContract } from "./schema.js";
 import { type RuntimeStageAcceptanceValidation } from "./runtime-types.js";
+export declare function stageRecordFromState(state: CompiledState | null, stageId: string): Record<string, unknown> | null;
+export declare function validateResolvedStageAcceptance(dirPath: string, options: {
+    stageId: string;
+    acceptance?: RuntimeStageAcceptance;
+    counts?: Record<string, number>;
+}): RuntimeStageAcceptanceValidation;
 export declare function validateStageContractAcceptance(dirPath: string, contract?: RuntimeStageContract | null): RuntimeStageAcceptanceValidation;