@interf/compiler 0.22.0 → 0.33.0

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

@@ -0,0 +1,160 @@
+import { z } from "zod";
+import { InterfIdPattern, isInterfRelativePath } from "./schema.js";
+export declare const ProjectNamePattern: RegExp;
+export declare const ProjectNameSchema: z.ZodString;
+export type ProjectName = z.infer<typeof ProjectNameSchema>;
+/**
+ * Drift verdict for a Project's source binding.
+ *
+ *   fresh    — latest Source Manifest matches the latest Context Graph
+ *   drifted  — a newer Source Manifest differs from latest Context Graph
+ *   missing  — retained for older records where local Source was unreadable
+ *   unknown  — no Source Manifest exists yet
+ */
+export declare const DriftKindSchema: z.ZodEnum<{
+    unknown: "unknown";
+    missing: "missing";
+    fresh: "fresh";
+    drifted: "drifted";
+}>;
+export type DriftKind = z.infer<typeof DriftKindSchema>;
+/**
+ * Per-Project Source state. Computed from the latest Source Manifest, not by
+ * reading the Source locator directly.
+ */
+export declare const ProjectSourceStateSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-project-source-state">;
+    version: z.ZodLiteral<1>;
+    project_id: z.ZodString;
+    file_index_hash: z.ZodNullable<z.ZodString>;
+    file_count: z.ZodNumber;
+    last_observed_at: z.ZodString;
+    drift_kind: z.ZodEnum<{
+        unknown: "unknown";
+        missing: "missing";
+        fresh: "fresh";
+        drifted: "drifted";
+    }>;
+    drift_summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ProjectSourceState = z.infer<typeof ProjectSourceStateSchema>;
+export declare const TraceSchema: z.ZodObject<{
+    kind: z.ZodString;
+    label: z.ZodString;
+    count: z.ZodOptional<z.ZodNumber>;
+    total: z.ZodOptional<z.ZodNumber>;
+    passed: z.ZodOptional<z.ZodBoolean>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type Trace = z.infer<typeof TraceSchema>;
+export declare const TracesSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-context-graph-traces">;
+    version: z.ZodLiteral<1>;
+    generated_at: z.ZodString;
+    graph_id: z.ZodString;
+    project_id: z.ZodString;
+    files_processed: z.ZodNumber;
+    files_total: z.ZodNumber;
+    checks_passed: z.ZodNumber;
+    checks_total: z.ZodNumber;
+    ready: z.ZodBoolean;
+    pages_read: z.ZodOptional<z.ZodNumber>;
+    charts_extracted: z.ZodOptional<z.ZodNumber>;
+    entities_found: z.ZodOptional<z.ZodNumber>;
+    items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        label: z.ZodString;
+        count: z.ZodOptional<z.ZodNumber>;
+        total: z.ZodOptional<z.ZodNumber>;
+        passed: z.ZodOptional<z.ZodBoolean>;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type Traces = z.infer<typeof TracesSchema>;
+export declare const ContextGraphLocatorSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "local-path": "local-path";
+        "remote-url": "remote-url";
+        "api-served": "api-served";
+    }>;
+    value: z.ZodString;
+}, z.core.$strict>;
+export type ContextGraphLocator = z.infer<typeof ContextGraphLocatorSchema>;
+export declare const ContextGraphSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-context-graph">;
+    version: z.ZodLiteral<1>;
+    graph_id: z.ZodString;
+    project_id: z.ZodString;
+    build_run_id: z.ZodString;
+    source_state_id: z.ZodString;
+    created_at: z.ZodString;
+    ready: z.ZodBoolean;
+    locator: z.ZodObject<{
+        kind: z.ZodEnum<{
+            "local-path": "local-path";
+            "remote-url": "remote-url";
+            "api-served": "api-served";
+        }>;
+        value: z.ZodString;
+    }, z.core.$strict>;
+    artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        artifact_id: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            skipped: "skipped";
+            ready: "ready";
+            not_ready: "not_ready";
+        }>;
+        built_by_stages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        check_results: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            check_id: z.ZodString;
+            kind: z.ZodEnum<{
+                file_exists: "file_exists";
+                source_manifest_valid: "source_manifest_valid";
+                min_file_count: "min_file_count";
+                min_file_count_matches_source: "min_file_count_matches_source";
+                source_summary_folders: "source_summary_folders";
+                source_page_coverage: "source_page_coverage";
+                frontmatter_valid: "frontmatter_valid";
+                frontmatter_required_keys: "frontmatter_required_keys";
+                frontmatter_nonempty_keys: "frontmatter_nonempty_keys";
+                source_refs_required: "source_refs_required";
+                wikilinks_valid: "wikilinks_valid";
+                must_not_contain: "must_not_contain";
+                must_contain: "must_contain";
+                qa_match: "qa_match";
+            }>;
+            passed: z.ZodBoolean;
+            required: z.ZodBoolean;
+            summary: z.ZodString;
+            details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            evaluated_at: z.ZodString;
+        }, z.core.$strict>>>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    traces: z.ZodObject<{
+        kind: z.ZodLiteral<"interf-context-graph-traces">;
+        version: z.ZodLiteral<1>;
+        generated_at: z.ZodString;
+        graph_id: z.ZodString;
+        project_id: z.ZodString;
+        files_processed: z.ZodNumber;
+        files_total: z.ZodNumber;
+        checks_passed: z.ZodNumber;
+        checks_total: z.ZodNumber;
+        ready: z.ZodBoolean;
+        pages_read: z.ZodOptional<z.ZodNumber>;
+        charts_extracted: z.ZodOptional<z.ZodNumber>;
+        entities_found: z.ZodOptional<z.ZodNumber>;
+        items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            label: z.ZodString;
+            count: z.ZodOptional<z.ZodNumber>;
+            total: z.ZodOptional<z.ZodNumber>;
+            passed: z.ZodOptional<z.ZodBoolean>;
+            detail: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ContextGraph = z.infer<typeof ContextGraphSchema>;
+export { isInterfRelativePath, InterfIdPattern };

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

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { ArtifactStatusSchema, InterfIdPattern, isInterfRelativePath, } from "./schema.js";
+// ───────────────────────────────────────────────────────────────────────────
+// Project — the durable Source binding and selected Build Plan container.
+//
+// A Project binds a Source (folder), execution agents, Project activity,
+// and one selected Build Plan. The Build Plan owns intent, requested
+// Artifacts, checks, Build instructions, and optional source context.
+// Each Build produces one Context Graph.
+//
+// Project identity = `path + machine_id` (same folder on different machines
+// is a different Project). The `id` here is the user-facing handle, derived
+// from the source folder basename + locator hash at create time.
+// ───────────────────────────────────────────────────────────────────────────
+export const ProjectNamePattern = /^[a-z0-9][a-z0-9-]*$/;
+const RESERVED_PROJECT_NAMES = new Set(["tests", "build-plans"]);
+export const ProjectNameSchema = z
+    .string()
+    .regex(ProjectNamePattern, "Project names must use lowercase letters, numbers, and dashes only.")
+    .refine((value) => !RESERVED_PROJECT_NAMES.has(value), "Project name is reserved.");
+/**
+ * Drift verdict for a Project's source binding.
+ *
+ *   fresh    — latest Source Manifest matches the latest Context Graph
+ *   drifted  — a newer Source Manifest differs from latest Context Graph
+ *   missing  — retained for older records where local Source was unreadable
+ *   unknown  — no Source Manifest exists yet
+ */
+export const DriftKindSchema = z.enum(["fresh", "drifted", "missing", "unknown"]);
+/**
+ * Per-Project Source state. Computed from the latest Source Manifest, not by
+ * reading the Source locator directly.
+ */
+export const ProjectSourceStateSchema = z.object({
+    kind: z.literal("interf-project-source-state"),
+    version: z.literal(1),
+    project_id: z.string().min(1),
+    file_index_hash: z.string().min(1).nullable(),
+    file_count: z.number().int().min(0),
+    last_observed_at: z.string().min(1),
+    drift_kind: DriftKindSchema,
+    drift_summary: z.string().min(1).optional(),
+}).strict();
+// ───────────────────────────────────────────────────────────────────────────
+// Trace — per-claim provenance emitted per file processed by Interf.
+//
+// Traces are the visible product: "20 of 20 files processed, 847 pages
+// read, 18 charts extracted, 92 entities found, 12 checks passed."
+// Each trace rolls up one quantifiable piece of evidence.
+// ───────────────────────────────────────────────────────────────────────────
+export const TraceSchema = z.object({
+    kind: z.string().min(1),
+    label: z.string().min(1),
+    count: z.number().int().min(0).optional(),
+    total: z.number().int().min(0).optional(),
+    passed: z.boolean().optional(),
+    detail: z.string().min(1).optional(),
+}).strict();
+export const TracesSchema = z.object({
+    kind: z.literal("interf-context-graph-traces"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    graph_id: z.string().min(1),
+    project_id: z.string().min(1),
+    files_processed: z.number().int().min(0),
+    files_total: z.number().int().min(0),
+    checks_passed: z.number().int().min(0),
+    checks_total: z.number().int().min(0),
+    ready: z.boolean(),
+    /**
+     * Phase B quantitative signals — summed across all Artifacts that emitted
+     * the corresponding count in `CheckResult.details`. Optional because per-stage
+     * counters are opt-in: a stage that processes PDFs may report pages_read;
+     * a chart-extractor reports charts_extracted; an NER stage reports
+     * entities_found. Stages that don't know don't lie.
+     */
+    pages_read: z.number().int().min(0).optional(),
+    charts_extracted: z.number().int().min(0).optional(),
+    entities_found: z.number().int().min(0).optional(),
+    items: z.array(TraceSchema).default([]),
+}).strict();
+// ───────────────────────────────────────────────────────────────────────────
+// Context Graph — what Interf builds from a Project.
+//
+// Portable: exportable as a self-contained bundle.
+// Persistent: each Build produces a new Context Graph; old flows preserved.
+// Updatable: when source drifts, a new Context Graph is built via resync.
+//
+// The Context Graph wraps the per-build output and surfaces artifacts
+// + traces as first-class fields.
+// ───────────────────────────────────────────────────────────────────────────
+export const ContextGraphLocatorSchema = z.object({
+    kind: z.enum(["local-path", "remote-url", "api-served"]),
+    value: z.string().min(1),
+}).strict();
+export const ContextGraphSchema = z.object({
+    kind: z.literal("interf-context-graph"),
+    version: z.literal(1),
+    graph_id: z.string().min(1),
+    project_id: z.string().min(1),
+    build_run_id: z.string().min(1),
+    source_state_id: z.string().min(1),
+    created_at: z.string().min(1),
+    ready: z.boolean(),
+    locator: ContextGraphLocatorSchema,
+    artifacts: z.array(ArtifactStatusSchema).default([]),
+    traces: TracesSchema,
+}).strict();
+// Project service request/resource schemas live in
+// `src/packages/runtime/schemas/projects.ts`, the single local-service ABI
+// source of truth. This contracts module keeps only product-level Project,
+// Context Graph, and trace contracts that do not define HTTP resources.
+export { isInterfRelativePath, InterfIdPattern };