@interf/compiler 0.6.1 → 0.6.4

package/dist/packages/compiler/state-view.js

@@ -0,0 +1,103 @@
+import { basename, relative } from "node:path";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { discoverSourceFiles } from "./discovery.js";
+import { readInterfConfig, resolveSourceFolderPath } from "../project-model/interf-detect.js";
+import { loadCompiledViewSpec, saveCompiledViewSpec, } from "./state-io.js";
+import { rawSnapshotPath } from "./state-paths.js";
+import { compiledRuntimeRoot, workflowPackagePathForCompiled } from "./compiled-paths.js";
+import { readCompiledSchemaFile } from "./compiled-schema.js";
+import { getActiveCompiledWorkflow, resolveRequiredCompiledWorkflowFromConfig } from "../workflow-package/workflow-definitions.js";
+export function ensureCompiledViewSpec(dirPath) {
+    const existing = loadCompiledViewSpec(dirPath);
+    const now = new Date().toISOString();
+    const compiledName = readInterfConfig(dirPath)?.name ?? basename(dirPath);
+    const defaults = buildDefaultCompiledViewSpec(dirPath, compiledName, now);
+    if (existing) {
+        const normalized = normalizeCompiledViewSpec(existing, defaults);
+        if (JSON.stringify(normalized) !== JSON.stringify(existing)) {
+            saveCompiledViewSpec(dirPath, normalized);
+        }
+        return normalized;
+    }
+    saveCompiledViewSpec(dirPath, defaults);
+    return defaults;
+}
+export function ensureCompiledRawSnapshot(dirPath) {
+    const now = new Date().toISOString();
+    const config = readInterfConfig(dirPath);
+    const compiledName = config?.name ?? basename(dirPath);
+    const sourcePath = resolveSourceFolderPath(dirPath, config);
+    const discovery = discoverSourceFiles(sourcePath, dirPath);
+    const sampleFiles = [...discovery.sourceFiles]
+        .sort((a, b) => a.length - b.length || a.localeCompare(b))
+        .slice(0, 10);
+    const sourceRoot = relative(dirPath, sourcePath) || ".";
+    const artifact = {
+        kind: "compiled-raw-snapshot",
+        version: 1,
+        generated_at: now,
+        target_name: compiledName,
+        source_root: sourceRoot,
+        raw_root: sourceRoot,
+        source_total: discovery.totalCount,
+        sample_files: sampleFiles,
+    };
+    mkdirSync(compiledRuntimeRoot(dirPath), { recursive: true });
+    writeFileSync(rawSnapshotPath(dirPath), JSON.stringify(artifact, null, 2) + "\n");
+    return artifact;
+}
+export function normalizeCompiledViewSpec(existing, defaults) {
+    const resolvedDefaults = defaults ?? existing;
+    return {
+        ...resolvedDefaults,
+        ...existing,
+        cards: Array.isArray(existing.cards) && existing.cards.length > 0
+            ? existing.cards.map((card) => {
+                if (card.format !== "fraction" || card.denominator_metric)
+                    return card;
+                const defaultCard = resolvedDefaults.cards.find((candidate) => candidate.id === card.id);
+                return {
+                    ...card,
+                    denominator_metric: defaultCard?.denominator_metric ?? "stage_total",
+                };
+            })
+            : resolvedDefaults.cards,
+        sections: Array.isArray(existing.sections) && existing.sections.length > 0 ? existing.sections : resolvedDefaults.sections,
+        graph_scope: Array.isArray(existing.graph_scope) && existing.graph_scope.length > 0
+            ? existing.graph_scope
+            : resolvedDefaults.graph_scope,
+    };
+}
+function buildDefaultCompiledViewSpec(dirPath, compiledName, generatedAt) {
+    const config = readInterfConfig(dirPath);
+    const workflowId = resolveRequiredCompiledWorkflowFromConfig(config, `.interf/interf.json for ${dirPath}`);
+    const workflow = getActiveCompiledWorkflow(dirPath, workflowId);
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(dirPath));
+    const outputDocumentPaths = (schema?.zones ?? [])
+        .filter((zone) => zone.role === "output" && zone.kind !== "runtime")
+        .map((zone) => zone.path);
+    const defaultNote = (schema?.zones ?? []).find((zone) => zone.role === "output" && zone.kind === "file")?.path ?? null;
+    return {
+        kind: "compiled-view-spec",
+        version: 2,
+        generated_at: generatedAt,
+        target_name: compiledName,
+        health_source: ".interf/runtime/health.json",
+        state_source: ".interf/runtime/state.json",
+        default_note: defaultNote,
+        graph_scope: outputDocumentPaths,
+        cards: [
+            { id: "source-total", label: "Source Files", metric: "source_total", format: "number" },
+            { id: "stage-total", label: "Stages", metric: "stage_total", format: "number" },
+            { id: "completed-stages", label: "Completed", metric: "completed_stages", denominator_metric: "stage_total", format: "fraction" },
+        ],
+        sections: [
+            { id: "status", type: "status", title: "Compile Status", path: ".interf/runtime/health.json" },
+            { id: "cards", type: "cards", title: "Key Metrics", path: ".interf/runtime/health.json" },
+            ...(outputDocumentPaths.length > 0
+                ? [{ id: "outputs", type: "documents", title: "Output Zones", paths: outputDocumentPaths }]
+                : []),
+            { id: "workflow", type: "documents", title: "Workflow Docs", paths: ["workflow/README.md", ...workflow.stages.map((stage) => `workflow/compile/stages/${stage.skillDir}`)] },
+        ],
+    };
+}

package/dist/packages/compiler/state.d.ts

@@ -0,0 +1,7 @@
+export type { RuntimeStatus, CompiledStage, CompiledState, CompiledHealth, ViewSection, ViewCard, CompiledViewSpec, CompiledRawSnapshot, } from "./lib/schema.js";
+export { statePath, healthPath, viewSpecPath, rawSnapshotPath, } from "./state-paths.js";
+export { loadState, saveState, loadCompiledHealth, saveCompiledHealth, loadCompiledViewSpec, loadCompiledRawSnapshot, saveCompiledViewSpec, initCompiledState, } from "./state-io.js";
+export { refreshCompiledArtifacts, } from "./state-artifacts.js";
+export { computeCompiledHealth, resolveCompiledStatus, resolveCompiledStage, } from "./state-health.js";
+export { ensureCompiledViewSpec, ensureCompiledRawSnapshot, normalizeCompiledViewSpec, } from "./state-view.js";
+export declare function initializeCompiledRuntimeState(dirPath: string): void;

package/dist/packages/compiler/state.js

@@ -0,0 +1,12 @@
+export { statePath, healthPath, viewSpecPath, rawSnapshotPath, } from "./state-paths.js";
+export { loadState, saveState, loadCompiledHealth, saveCompiledHealth, loadCompiledViewSpec, loadCompiledRawSnapshot, saveCompiledViewSpec, initCompiledState, } from "./state-io.js";
+export { refreshCompiledArtifacts, } from "./state-artifacts.js";
+export { computeCompiledHealth, resolveCompiledStatus, resolveCompiledStage, } from "./state-health.js";
+export { ensureCompiledViewSpec, ensureCompiledRawSnapshot, normalizeCompiledViewSpec, } from "./state-view.js";
+import { saveEmptyCompiledInventory, initCompiledState, saveState } from "./state-io.js";
+import { refreshCompiledArtifacts } from "./state-artifacts.js";
+export function initializeCompiledRuntimeState(dirPath) {
+    saveState(dirPath, initCompiledState());
+    saveEmptyCompiledInventory(dirPath);
+    refreshCompiledArtifacts(dirPath, { ensureViewSpec: true });
+}

package/dist/packages/compiler/validate-compiled.d.ts

@@ -0,0 +1,27 @@
+export interface CompiledValidationSummary {
+    config_present: boolean;
+    config_valid: boolean;
+    config_type_match: boolean;
+    workflow_present: boolean;
+    workflow_valid: boolean;
+    schema_present: boolean;
+    schema_valid: boolean;
+}
+export interface CompiledStageValidation {
+    ok: boolean;
+    required: boolean;
+    stage: string;
+    summary: string;
+    counts: Record<string, number>;
+    checks: Record<string, boolean>;
+    errors: string[];
+}
+export interface CompiledWorkflowValidation extends CompiledStageValidation {
+    stage_results: Record<string, boolean>;
+}
+export declare function validateCompiled(dirPath: string): CompiledValidationSummary;
+export declare function validateCompiledStage(dirPath: string, stageId: string): CompiledStageValidation;
+export declare function validateCompiledWorkflow(dirPath: string): CompiledWorkflowValidation;
+export declare function validateCompiledSummarize(dirPath: string): CompiledStageValidation;
+export declare function validateCompiledStructure(dirPath: string): CompiledStageValidation;
+export declare function validateCompiledCompile(dirPath: string): CompiledWorkflowValidation;

package/dist/packages/compiler/validate-compiled.js

@@ -0,0 +1,241 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { discoverSourceFiles } from "./discovery.js";
+import { WORKFLOW_SCHEMA_FILE, compiledZoneAbsolutePath, findCompiledSchemaZone, readCompiledSchemaFile, workflowSchemaExists, } from "./compiled-schema.js";
+import { resolveSourceFolderPath } from "../project-model/interf-detect.js";
+import { compiledInterfConfigPath, workflowPackagePathForCompiled } from "./compiled-paths.js";
+import { readCompiledConfig } from "./validate.js";
+import { loadState } from "./state.js";
+import { validateResolvedStageAcceptance, stageRecordFromState } from "./runtime-acceptance.js";
+import { getActiveCompiledWorkflow, resolveRequiredCompiledWorkflowFromConfig, } from "../workflow-package/workflow-definitions.js";
+import { listFilesRecursive } from "../shared/filesystem.js";
+function workflowSchemaPresent(dirPath) {
+    return workflowSchemaExists(join(dirPath, ".interf", "workflow"));
+}
+function countZoneArtifacts(compiledPath, zonePath, kind) {
+    const absolutePath = compiledZoneAbsolutePath(compiledPath, { path: zonePath });
+    if (!existsSync(absolutePath))
+        return 0;
+    if (kind === "file")
+        return 1;
+    return listFilesRecursive(absolutePath).length;
+}
+function readWorkflowContext(dirPath) {
+    const config = readCompiledConfig(dirPath);
+    const workflowId = config.valid
+        ? resolveRequiredCompiledWorkflowFromConfig(config.value, `.interf/interf.json for ${dirPath}`)
+        : null;
+    let workflow = null;
+    if (workflowId) {
+        try {
+            workflow = getActiveCompiledWorkflow(dirPath, workflowId);
+        }
+        catch {
+            workflow = null;
+        }
+    }
+    const schema = readCompiledSchemaFile(workflowPackagePathForCompiled(dirPath));
+    const state = loadState(dirPath);
+    const sourceTotal = config.valid
+        ? discoverSourceFiles(resolveSourceFolderPath(dirPath, config.value), dirPath).totalCount
+        : 0;
+    return {
+        config,
+        workflow,
+        schema,
+        state,
+        sourceTotal,
+        workflowId,
+    };
+}
+function stageRequired(sourceTotal, writeCounts, stageRecordPresent) {
+    return sourceTotal > 0 || writeCounts > 0 || stageRecordPresent;
+}
+function zoneWriteCount(compiledPath, schema, stage) {
+    const zoneCounts = {};
+    let total = 0;
+    for (const zoneId of stage.writes) {
+        const zone = findCompiledSchemaZone(schema, zoneId);
+        if (!zone)
+            continue;
+        const count = countZoneArtifacts(compiledPath, zone.path, zone.kind);
+        zoneCounts[zoneId] = count;
+        total += count;
+    }
+    return { total, zoneCounts };
+}
+function mergeValidationCounts(sourceTotal, stageRecord, zoneCounts) {
+    const merged = {
+        source_total: sourceTotal,
+        ...zoneCounts,
+    };
+    const stageCounts = stageRecord?.counts;
+    if (stageCounts && typeof stageCounts === "object" && !Array.isArray(stageCounts)) {
+        for (const [key, value] of Object.entries(stageCounts)) {
+            if (typeof value === "number" && Number.isFinite(value)) {
+                merged[key] = value;
+            }
+        }
+    }
+    return merged;
+}
+export function validateCompiled(dirPath) {
+    const context = readWorkflowContext(dirPath);
+    return {
+        config_present: context.config.present,
+        config_valid: context.config.valid,
+        config_type_match: context.config.typeMatch(),
+        workflow_present: existsSync(join(dirPath, ".interf", "workflow", "workflow.json")),
+        workflow_valid: context.workflow !== null,
+        schema_present: workflowSchemaPresent(dirPath),
+        schema_valid: context.schema !== null,
+    };
+}
+export function validateCompiledStage(dirPath, stageId) {
+    const context = readWorkflowContext(dirPath);
+    const checks = {
+        config_present: context.config.present,
+        config_valid: context.config.valid,
+        config_type_match: context.config.typeMatch(),
+        workflow_present: existsSync(join(dirPath, ".interf", "workflow", "workflow.json")),
+        workflow_valid: context.workflow !== null,
+        schema_present: workflowSchemaPresent(dirPath),
+        schema_valid: context.schema !== null,
+    };
+    const errors = [];
+    if (!checks.config_present)
+        errors.push(`Missing ${compiledInterfConfigPath(dirPath)}.`);
+    else if (!checks.config_valid)
+        errors.push(`Could not parse ${compiledInterfConfigPath(dirPath)}.`);
+    else if (!checks.config_type_match)
+        errors.push("Config is not a compiled context.");
+    if (!checks.workflow_present)
+        errors.push("Missing .interf/workflow/workflow.json.");
+    else if (!checks.workflow_valid)
+        errors.push("Could not load the active workflow package.");
+    if (!checks.schema_present)
+        errors.push(`Missing .interf/workflow/${WORKFLOW_SCHEMA_FILE}.`);
+    else if (!checks.schema_valid)
+        errors.push(`Could not parse .interf/workflow/${WORKFLOW_SCHEMA_FILE}.`);
+    const workflowStage = context.workflow?.stages.find((stage) => stage.id === stageId) ?? null;
+    checks.stage_present = workflowStage !== null;
+    if (!checks.stage_present) {
+        errors.push(`Workflow does not declare stage "${stageId}".`);
+    }
+    const stageRecord = stageRecordFromState(context.state, stageId);
+    checks.stage_record_present = stageRecord !== null;
+    checks.stage_finished = Boolean(stageRecord?.finished_at);
+    checks.stage_succeeded = stageRecord?.status === "succeeded";
+    const writeCounts = workflowStage && context.schema
+        ? zoneWriteCount(dirPath, context.schema, workflowStage)
+        : { total: 0, zoneCounts: {} };
+    const acceptanceCounts = mergeValidationCounts(context.sourceTotal, stageRecord, writeCounts.zoneCounts);
+    const required = stageRequired(context.sourceTotal, writeCounts.total, checks.stage_record_present);
+    let acceptanceErrors = [];
+    if (workflowStage && context.schema) {
+        const acceptanceValidation = validateResolvedStageAcceptance(dirPath, {
+            stageId,
+            acceptance: workflowStage.acceptance,
+            counts: acceptanceCounts,
+        });
+        checks.acceptance_ok = acceptanceValidation.ok;
+        acceptanceErrors = acceptanceValidation.failures;
+    }
+    else {
+        checks.acceptance_ok = false;
+    }
+    if (required && checks.stage_record_present && !checks.stage_finished) {
+        errors.push(`Stage "${stageId}" has no finished_at proof in runtime state.`);
+    }
+    if (required && checks.stage_record_present && !checks.stage_succeeded) {
+        errors.push(`Stage "${stageId}" is not marked succeeded in runtime state.`);
+    }
+    if (required) {
+        errors.push(...acceptanceErrors);
+    }
+    const ok = required ? errors.length === 0 : errors.length === 0;
+    const summary = !required
+        ? `Stage "${stageId}" is not required yet.`
+        : ok
+            ? `Stage "${stageId}" verified.`
+            : `Stage "${stageId}" failed — ${errors[0] ?? "acceptance not satisfied."}`;
+    return {
+        ok,
+        required,
+        stage: stageId,
+        summary,
+        counts: {
+            ...acceptanceCounts,
+            write_artifacts: writeCounts.total,
+            declared_write_zones: workflowStage?.writes.length ?? 0,
+        },
+        checks,
+        errors,
+    };
+}
+export function validateCompiledWorkflow(dirPath) {
+    const context = readWorkflowContext(dirPath);
+    const checks = {
+        config_present: context.config.present,
+        config_valid: context.config.valid,
+        config_type_match: context.config.typeMatch(),
+        workflow_present: existsSync(join(dirPath, ".interf", "workflow", "workflow.json")),
+        workflow_valid: context.workflow !== null,
+        schema_present: workflowSchemaPresent(dirPath),
+        schema_valid: context.schema !== null,
+    };
+    if (!context.workflow) {
+        const errors = ["Could not load the active workflow package."];
+        return {
+            ok: false,
+            required: true,
+            stage: "workflow",
+            summary: `Compiled workflow failed — ${errors[0]}`,
+            counts: { source_total: context.sourceTotal, stage_total: 0, completed_stages: 0 },
+            checks,
+            errors,
+            stage_results: {},
+        };
+    }
+    const stageResults = {};
+    const errors = [];
+    let completedStages = 0;
+    let failedStage = "compiled";
+    for (const stage of context.workflow.stages) {
+        const validation = validateCompiledStage(dirPath, stage.id);
+        stageResults[stage.id] = validation.ok;
+        if (validation.ok) {
+            completedStages += 1;
+            continue;
+        }
+        failedStage = stage.id;
+        errors.push(...validation.errors);
+        break;
+    }
+    const ok = errors.length === 0;
+    return {
+        ok,
+        required: context.sourceTotal > 0,
+        stage: failedStage,
+        summary: ok
+            ? `Compiled workflow verified — ${completedStages}/${context.workflow.stages.length} stages satisfied.`
+            : `Compiled workflow failed — ${errors[0] ?? "stage acceptance not satisfied."}`,
+        counts: {
+            source_total: context.sourceTotal,
+            stage_total: context.workflow.stages.length,
+            completed_stages: completedStages,
+        },
+        checks,
+        errors,
+        stage_results: stageResults,
+    };
+}
+export function validateCompiledSummarize(dirPath) {
+    return validateCompiledStage(dirPath, "summarize");
+}
+export function validateCompiledStructure(dirPath) {
+    return validateCompiledStage(dirPath, "structure");
+}
+export function validateCompiledCompile(dirPath) {
+    return validateCompiledWorkflow(dirPath);
+}

package/dist/packages/compiler/validate-helpers.d.ts

@@ -0,0 +1,12 @@
+export declare function asStringArray(value: unknown): string[];
+export declare function asRejectedEntries(value: unknown): Array<{
+    path: string;
+    reason: string;
+}>;
+export declare function asFileEntries(value: unknown): Array<{
+    file: string;
+}>;
+export declare function isSubset(left: Set<string>, right: Set<string>): boolean;
+export declare function setsEqual(left: Set<string>, right: Set<string>): boolean;
+export declare function setIntersectionSize(left: Set<string>, right: Set<string>): number;
+export declare function dedupeStrings(values: string[]): string[];

package/dist/packages/compiler/validate-helpers.js

@@ -0,0 +1,41 @@
+export function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}
+export function asRejectedEntries(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => !!item &&
+        typeof item === "object" &&
+        typeof item.path === "string" &&
+        typeof item.reason === "string");
+}
+export function asFileEntries(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => !!item &&
+        typeof item === "object" &&
+        typeof item.file === "string");
+}
+export function isSubset(left, right) {
+    for (const item of left) {
+        if (!right.has(item))
+            return false;
+    }
+    return true;
+}
+export function setsEqual(left, right) {
+    return left.size === right.size && isSubset(left, right);
+}
+export function setIntersectionSize(left, right) {
+    let count = 0;
+    for (const item of left) {
+        if (right.has(item))
+            count += 1;
+    }
+    return count;
+}
+export function dedupeStrings(values) {
+    return Array.from(new Set(values));
+}

package/dist/packages/compiler/validate.d.ts

@@ -0,0 +1,21 @@
+import { readInterfConfig } from "../project-model/interf-detect.js";
+export declare function readCompiledConfig(dirPath: string): {
+    present: boolean;
+    valid: boolean;
+    value: ReturnType<typeof readInterfConfig>;
+    typeMatch(): boolean;
+};
+export declare function validateSynthFiles(files: string[], options?: {
+    requiredFrontmatterKeys?: string[];
+}): {
+    invalid_frontmatter: number;
+    short_abstracts: number;
+};
+export declare function countBrokenWikilinks(compiledRoot: string, noteIndexRoots: string[], linkScanRoots: string[]): number;
+export declare function asNumber(value: unknown): number;
+export declare function isOutputMarkdownFile(filePath: string): boolean;
+export declare function safeReadText(filePath: string): string | null;
+export declare function extractSynthAbstract(frontmatter: Record<string, unknown>, body: string): string | null;
+export declare function countSynthAbstractWords(frontmatter: Record<string, unknown>, body: string): number;
+export { validateCompiled, validateCompiledStage, validateCompiledWorkflow, validateCompiledSummarize, validateCompiledStructure, validateCompiledCompile, } from "./validate-compiled.js";
+export type { CompiledValidationSummary, CompiledStageValidation, CompiledWorkflowValidation, } from "./validate-compiled.js";