@iq-context/core 0.1.0 → 0.3.0

package/dist/invariantSnapshot.js

@@ -0,0 +1,219 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseProjectConfigFile } from "./config.js";
+import { getProjectPaths } from "./state.js";
+import { parseCaptureEntry, parseFocusState, parseProjectState, parseResumeState, parseWorkstreamState, } from "./stateSchemas.js";
+import { resolveWorkstreamPath, validateWorkstreamId } from "./workstreamId.js";
+function ok(value) {
+    return { loaded: true, value };
+}
+function failed(error) {
+    return { loaded: false, error: error instanceof Error ? error.message : String(error) };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function loadParsedJson(filePath, parse) {
+    try {
+        if (!fs.existsSync(filePath)) {
+            return { loaded: false, error: `Missing required state file: ${filePath}` };
+        }
+        const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        return ok(parse(raw, filePath));
+    }
+    catch (error) {
+        return failed(error);
+    }
+}
+/**
+ * Preserves the id validation `loadProjectState` performs, so a traversal
+ * attempt stays a load failure instead of degrading to a referential violation.
+ */
+function loadProjectStateResult(projectStatePath) {
+    const result = loadParsedJson(projectStatePath, parseProjectState);
+    if (!result.loaded) {
+        return result;
+    }
+    try {
+        for (const workstreamId of result.value.workstreams) {
+            validateWorkstreamId(workstreamId, `persisted workstream id in ${projectStatePath}`);
+        }
+    }
+    catch (error) {
+        return failed(error);
+    }
+    return result;
+}
+/** Symmetric with loadProjectStateResult: loadFocusState validates this id too. */
+function loadFocusStateResult(focusStatePath) {
+    const result = loadParsedJson(focusStatePath, parseFocusState);
+    if (!result.loaded) {
+        return result;
+    }
+    try {
+        validateWorkstreamId(result.value.current_workstream_id, `current_workstream_id in ${focusStatePath}`);
+    }
+    catch (error) {
+        return failed(error);
+    }
+    return result;
+}
+function loadConfig(configPath) {
+    try {
+        return ok(parseProjectConfigFile(configPath));
+    }
+    catch (error) {
+        return failed(error);
+    }
+}
+function loadPointer(pointerPath) {
+    try {
+        if (!fs.existsSync(pointerPath)) {
+            return ok(null);
+        }
+        const value = fs.readFileSync(pointerPath, "utf8").trim();
+        if (value.length === 0) {
+            return ok(null);
+        }
+        return ok(validateWorkstreamId(value, `workstream pointer in ${pointerPath}`));
+    }
+    catch (error) {
+        return failed(error);
+    }
+}
+/**
+ * A failure here means the listing is unknown, which is deliberately distinct
+ * from a successfully read empty directory. Missing and unreadable are both
+ * failures because neither yields a trustworthy list; doctor reports the
+ * directory's absence separately.
+ */
+function enumerateWorkstreamDirs(workstreamsDir) {
+    let entries;
+    try {
+        if (!fs.existsSync(workstreamsDir)) {
+            return { loaded: false, error: `Missing workstreams directory: ${workstreamsDir}` };
+        }
+        if (!fs.statSync(workstreamsDir).isDirectory()) {
+            return { loaded: false, error: `Not a directory: ${workstreamsDir}` };
+        }
+        entries = fs.readdirSync(workstreamsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        return failed(error);
+    }
+    const valid = [];
+    const invalid = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        // Hidden entries are never workstreams; an interrupted atomic write can
+        // leave scratch entries here, and residue must not read as a bad name.
+        if (entry.name.startsWith(".")) {
+            continue;
+        }
+        try {
+            validateWorkstreamId(entry.name, "persisted workstream directory name");
+            valid.push(entry.name);
+        }
+        catch {
+            invalid.push(entry.name);
+        }
+    }
+    return ok({ valid: valid.sort(), invalid: invalid.sort() });
+}
+function loadCaptureLog(capturePath) {
+    const results = [];
+    let content;
+    try {
+        if (!fs.existsSync(capturePath)) {
+            return results;
+        }
+        content = fs.readFileSync(capturePath, "utf8");
+    }
+    catch (error) {
+        return [{ loaded: false, kind: "syntax", error: messageOf(error) }];
+    }
+    for (const [index, line] of content.split(/\r?\n/).entries()) {
+        if (line.trim().length === 0) {
+            continue;
+        }
+        const source = `${capturePath}:${index + 1}`;
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch (error) {
+            results.push({ loaded: false, kind: "syntax", error: `${source}: ${messageOf(error)}` });
+            continue;
+        }
+        try {
+            results.push({ loaded: true, value: parseCaptureEntry(raw, source) });
+        }
+        catch (error) {
+            results.push({ loaded: false, kind: "schema", error: messageOf(error) });
+        }
+    }
+    return results;
+}
+/**
+ * Every in-workstream read goes through resolveWorkstreamPath inside a try, so
+ * a symlinked file inside a real workstream directory becomes a load failure
+ * rather than a read outside .iq-context.
+ */
+function loadWorkstreamFile(projectRoot, workstreamId, fileName, parse) {
+    try {
+        return loadParsedJson(resolveWorkstreamPath(projectRoot, workstreamId, fileName), parse);
+    }
+    catch (error) {
+        return failed(error);
+    }
+}
+function loadOptionalJson(projectRoot, workstreamId, fileName) {
+    try {
+        const filePath = resolveWorkstreamPath(projectRoot, workstreamId, fileName);
+        if (!fs.existsSync(filePath)) {
+            return ok(null);
+        }
+        return ok(JSON.parse(fs.readFileSync(filePath, "utf8")));
+    }
+    catch (error) {
+        return failed(error);
+    }
+}
+function loadWorkstreamCaptures(projectRoot, workstreamId) {
+    let capturePath;
+    try {
+        capturePath = resolveWorkstreamPath(projectRoot, workstreamId, "captures.jsonl");
+    }
+    catch (error) {
+        // Containment, not syntax: grading this as a syntax failure would misreport
+        // why the file was rejected.
+        return [{ loaded: false, kind: "containment", error: messageOf(error) }];
+    }
+    return loadCaptureLog(capturePath);
+}
+export function loadInvariantSnapshot(projectRoot) {
+    const paths = getProjectPaths(projectRoot);
+    const workstreamDirs = enumerateWorkstreamDirs(paths.workstreamsDir);
+    const workstreams = workstreamDirs.loaded
+        ? workstreamDirs.value.valid.map((id) => ({
+            id,
+            state: loadWorkstreamFile(projectRoot, id, "state.json", parseWorkstreamState),
+            resume: loadWorkstreamFile(projectRoot, id, "resume-state.json", parseResumeState),
+            hostBindings: loadOptionalJson(projectRoot, id, "host-bindings.json"),
+            captures: loadWorkstreamCaptures(projectRoot, id),
+        }))
+        : [];
+    return {
+        projectRoot,
+        project: loadProjectStateResult(paths.projectStatePath),
+        focus: loadFocusStateResult(paths.focusStatePath),
+        config: loadConfig(paths.configPath),
+        pointer: loadPointer(paths.currentWorkstreamPath),
+        workstreamDirs,
+        workstreams,
+        projectCaptures: loadCaptureLog(path.join(projectRoot, ".iq-context", "captures.jsonl")),
+    };
+}
+//# sourceMappingURL=invariantSnapshot.js.map

package/dist/invariantSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariantSnapshot.js","sourceRoot":"","sources":["../src/invariantSnapshot.ts"],"names":[],"mappings":"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"}

package/dist/invariantTypes.d.ts

@@ -0,0 +1,100 @@
+import type { ProjectConfig } from "./config.js";
+import type { CaptureEntry, FocusState, ProjectState, ResumeState, WorkstreamState } from "./types.js";
+export type LoadResult<T> = {
+    loaded: true;
+    value: T;
+} | {
+    loaded: false;
+    error: string;
+};
+export interface HostBindings {
+    bindings: unknown[];
+}
+export declare const HOST_BINDINGS_SCHEMA_FIELDS: readonly ["bindings"];
+/**
+ * `containment` marks a path that escaped `.iq-context`, which is neither a
+ * JSON syntax problem nor a schema problem and must not be graded as either.
+ */
+export type CaptureLoadFailureKind = "syntax" | "schema" | "containment";
+export type CaptureLoadResult = {
+    loaded: true;
+    value: CaptureEntry;
+} | {
+    loaded: false;
+    error: string;
+    kind: CaptureLoadFailureKind;
+};
+export interface WorkstreamDirs {
+    valid: string[];
+    invalid: string[];
+}
+export interface WorkstreamSnapshot {
+    id: string;
+    state: LoadResult<WorkstreamState>;
+    resume: LoadResult<ResumeState>;
+    hostBindings: LoadResult<unknown>;
+    captures: CaptureLoadResult[];
+}
+export interface InvariantSnapshot {
+    projectRoot: string;
+    project: LoadResult<ProjectState>;
+    focus: LoadResult<FocusState>;
+    config: LoadResult<ProjectConfig>;
+    pointer: LoadResult<string | null>;
+    /** Failed enumeration must never masquerade as "no workstreams exist". */
+    workstreamDirs: LoadResult<WorkstreamDirs>;
+    /** Always empty when `workstreamDirs` failed to load. */
+    workstreams: WorkstreamSnapshot[];
+    projectCaptures: CaptureLoadResult[];
+}
+export type InvariantSeverity = "error" | "warning";
+export type InvariantScope = {
+    kind: "project" | "focus" | "config";
+} | {
+    kind: "workstream";
+    workstreamId: string;
+};
+export interface InvariantViolation {
+    invariantId: string;
+    severity: InvariantSeverity;
+    scope: InvariantScope;
+    message: string;
+}
+/**
+ * Four arms, so illegal states are unrepresentable: a "pass" cannot carry
+ * violations and a "skipped" cannot omit its reason.
+ */
+export type InvariantOutcome = {
+    status: "pass";
+} | {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "partial";
+    skippedScopes: string[];
+} | {
+    status: "violated";
+    violations: InvariantViolation[];
+    skippedScopes: string[];
+};
+/** Snapshot slots an invariant can declare a dependency on. */
+export type InvariantRequirement = "project" | "focus" | "config" | "pointer" | "workstreamDirs";
+/**
+ * `requires` is declarative so the evaluator can skip an invariant before it
+ * runs. Guarding inside each `evaluate` was tried and repeatedly forgotten,
+ * which turned unevaluable state into false passes; declaring the dependency
+ * makes that class of bug unrepresentable.
+ *
+ * No `severity` field: severity is carried per violation, so a nominal
+ * invariant-level severity could silently disagree with what it reports.
+ */
+export interface Invariant {
+    id: string;
+    description: string;
+    requires: InvariantRequirement[];
+    evaluate(snapshot: InvariantSnapshot): InvariantOutcome;
+}
+export interface InvariantEvaluation {
+    invariant: Invariant;
+    outcome: InvariantOutcome;
+}

package/dist/invariantTypes.js

@@ -0,0 +1,4 @@
+export const HOST_BINDINGS_SCHEMA_FIELDS = [
+    "bindings",
+];
+//# sourceMappingURL=invariantTypes.js.map

package/dist/invariantTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariantTypes.js","sourceRoot":"","sources":["../src/invariantTypes.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,UAAU;CACwC,CAAC"}

package/dist/invariants.d.ts

@@ -0,0 +1,13 @@
+import type { Invariant, InvariantEvaluation, InvariantOutcome, InvariantSnapshot, InvariantViolation } from "./invariantTypes.js";
+export declare function pass(): InvariantOutcome;
+export declare function skipped(reason: string): InvariantOutcome;
+/**
+ * Collapses a per-scope evaluation into an outcome.
+ *
+ * Precedence: a real contradiction outranks incompleteness, so violations win
+ * and carry the unevaluated scopes along for reporting. With no violations and
+ * at least one unevaluated scope the result is "partial", never "pass".
+ */
+export declare function resolveOutcome(violations: InvariantViolation[], skippedScopes?: string[]): InvariantOutcome;
+export declare const INVARIANTS: Invariant[];
+export declare function evaluateInvariants(snapshot: InvariantSnapshot): InvariantEvaluation[];