@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/scope-shrink.test.ts

@@ -1,633 +0,0 @@
-/**
- * Scope-shrink detection + classification + clean removal (US-005).
- *
- * Pins the hybrid-contract semantics decided in US-000 Task 3:
- *   - orphans = (covered by last scope) ∧ ¬(covered by current scope)
- *   - tombstones are NOT re-flagged on subsequent pulls
- *   - clean orphan: local missing OR hash matches + mtime ≤ syncedAt
- *   - dirty orphan: anything else
- *   - applyScopeShrink deletes clean orphans, leaves dirty files alone
- *     when `forceScopeShrink: true` but tombstones the journal entry
- */
-
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import * as crypto from "crypto";
-import {
-  buildScopeShrinkPlan,
-  applyScopeShrink,
-  ScopeShrinkBlockedError,
-} from "./scope-shrink.js";
-import type { SyncJournal } from "./types.js";
-
-function sha256(content: string): string {
-  return crypto.createHash("sha256").update(content).digest("hex");
-}
-
-function emptyJournal(): SyncJournal {
-  return { version: "2", lastSync: "", files: {}, pulls: [] };
-}
-
-describe("buildScopeShrinkPlan", () => {
-  let hqRoot: string;
-
-  beforeEach(() => {
-    hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-scope-shrink-"));
-  });
-
-  afterEach(() => {
-    fs.rmSync(hqRoot, { recursive: true, force: true });
-  });
-
-  it("returns empty plan when no orphans exist", () => {
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/meetings/a.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-05-01T00:00:00.000Z",
-          direction: "down",
-        },
-      },
-    };
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/"],
-    });
-    expect(plan.orphans).toEqual([]);
-    expect(plan.scopeChangeDetected).toBe(false);
-  });
-
-  it("flags files covered by lastPrefixSet but not currentPrefixSet as orphans", () => {
-    const meetingsAbs = path.join(
-      hqRoot,
-      "companies/indigo/meetings/a.md",
-    );
-    const scratchAbs = path.join(
-      hqRoot,
-      "companies/indigo/scratch/jacob/draft.md",
-    );
-    fs.mkdirSync(path.dirname(meetingsAbs), { recursive: true });
-    fs.mkdirSync(path.dirname(scratchAbs), { recursive: true });
-    fs.writeFileSync(meetingsAbs, "meetings");
-    fs.writeFileSync(scratchAbs, "draft");
-
-    const now = new Date().toISOString();
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/meetings/a.md": {
-          hash: sha256("meetings"),
-          size: 8,
-          syncedAt: now,
-          direction: "down",
-        },
-        "companies/indigo/scratch/jacob/draft.md": {
-          hash: sha256("draft"),
-          size: 5,
-          syncedAt: now,
-          direction: "down",
-        },
-      },
-    };
-    // Backdate the scratch file so mtime ≤ syncedAt.
-    const past = Date.now() - 60_000;
-    fs.utimesSync(scratchAbs, past / 1000, past / 1000);
-    fs.utimesSync(meetingsAbs, past / 1000, past / 1000);
-
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-    });
-    expect(plan.orphans.map((o) => o.path)).toEqual([
-      "companies/indigo/scratch/jacob/draft.md",
-    ]);
-    expect(plan.clean).toHaveLength(1);
-    expect(plan.dirty).toHaveLength(0);
-    expect(plan.scopeChangeDetected).toBe(true);
-  });
-
-  it("classifies a locally modified orphan as dirty (hash mismatch)", () => {
-    const abs = path.join(hqRoot, "companies/indigo/scratch/notes.md");
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, "ORIGINAL");
-
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/scratch/notes.md": {
-          hash: sha256("DIFFERENT"), // doesn't match what's on disk
-          size: 8,
-          syncedAt: new Date().toISOString(),
-          direction: "down",
-        },
-      },
-    };
-
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-    });
-    expect(plan.dirty).toHaveLength(1);
-    expect(plan.dirty[0]?.dirtyReason).toBe("hash-mismatch");
-  });
-
-  it("classifies a recently mtime-touched file as dirty", () => {
-    const abs = path.join(hqRoot, "companies/indigo/scratch/notes.md");
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, "ORIGINAL");
-
-    const syncedAt = new Date(Date.now() - 60_000).toISOString();
-    // Touch mtime forward, well past syncedAt + 1s grace.
-    const future = Date.now() + 10_000;
-    fs.utimesSync(abs, future / 1000, future / 1000);
-
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/scratch/notes.md": {
-          hash: sha256("ORIGINAL"), // hash matches, but mtime is forward
-          size: 8,
-          syncedAt,
-          direction: "down",
-        },
-      },
-    };
-
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-    });
-    expect(plan.dirty).toHaveLength(1);
-    expect(plan.dirty[0]?.dirtyReason).toBe("modified-after-sync");
-  });
-
-  it("treats a locally-missing orphan as clean (already removed by user)", () => {
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/scratch/gone.md": {
-          hash: sha256("gone"),
-          size: 4,
-          syncedAt: new Date().toISOString(),
-          direction: "down",
-        },
-      },
-    };
-
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-    });
-    expect(plan.clean).toHaveLength(1);
-    expect(plan.clean[0]?.path).toBe("companies/indigo/scratch/gone.md");
-  });
-
-  it("skips tombstoned entries (do not re-flag on subsequent pulls)", () => {
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/scratch/already.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-05-01T00:00:00.000Z",
-          direction: "down",
-          removedAt: "2026-05-02T00:00:00.000Z",
-          removedReason: "scope_shrink",
-        },
-      },
-    };
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-    });
-    expect(plan.orphans).toEqual([]);
-  });
-
-  it("skips push-only entries (direction: 'up')", () => {
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/scratch/local-only.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-05-01T00:00:00.000Z",
-          direction: "up",
-        },
-      },
-    };
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-    });
-    expect(plan.orphans).toEqual([]);
-  });
-
-  // US-006: a session transcript authored + pushed locally (direction: "up")
-  // under the push-only `sessions/{personUid}/` prefix must NEVER be orphaned by
-  // a scope shrink, even though `sessions/` sits outside the effective pull
-  // scope (it is subtracted from every pull scope as an excludePrefix). This is
-  // the authorship arm of the push-only contract: sessions are pushed, then
-  // never pulled, and the direction:"up" exemption keeps the author's own
-  // transcript from being pruned. Regression guard for AC4/AC6.
-  it("never orphans a locally-authored session (direction: 'up') when sessions is outside pull scope (US-006)", () => {
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "sessions/prs_1/2026-07-11T10-00-00.json": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-07-11T00:00:00.000Z",
-          direction: "up",
-        },
-      },
-    };
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      // Last pull saw everything ([""] = full scope); the current pull scope
-      // covers knowledge but NOT the push-only sessions prefix — exactly the
-      // shape the sessions exclusion produces on the download side.
-      lastPrefixSet: [""],
-      currentPrefixSet: ["knowledge/"],
-    });
-    expect(plan.orphans).toEqual([]);
-    expect(plan.scopeChangeDetected).toBe(false);
-  });
-
-  // ── Authorship guard ──────────────────────────────────────────────────────
-  // Sync mode decides whether you mirror OTHER people's files; it must never
-  // orphan content the caller authored. Owners hold their whole vault by
-  // role-bypass, so without this guard a `shared`/`custom` scope would treat
-  // their own un-granted work as "someone else's file" and prune it.
-
-  it("never orphans a file the caller authored, even out of scope", () => {
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/projects/mine.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-05-01T00:00:00.000Z",
-          direction: "down",
-          createdBySub: "sub-corey",
-        },
-      },
-    };
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-      callerSub: "sub-corey",
-    });
-    expect(plan.orphans).toEqual([]);
-    expect(plan.scopeChangeDetected).toBe(false);
-  });
-
-  it("orphans a file authored by someone else (mode stops mirroring others' files)", () => {
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/projects/theirs.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-05-01T00:00:00.000Z",
-          direction: "down",
-          createdBySub: "sub-jacob",
-        },
-      },
-    };
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-      callerSub: "sub-corey",
-      protectUnknownAuthors: true,
-    });
-    expect(plan.orphans.map((o) => o.path)).toEqual([
-      "companies/indigo/projects/theirs.md",
-    ]);
-  });
-
-  it("retains an unknown-author orphan when protectUnknownAuthors is set (conservative auto path)", () => {
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/projects/legacy.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-05-01T00:00:00.000Z",
-          direction: "down",
-          // no createdBySub — a legacy entry predating author stamping
-        },
-      },
-    };
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-      callerSub: "sub-corey",
-      protectUnknownAuthors: true,
-    });
-    expect(plan.orphans).toEqual([]);
-  });
-
-  it("prunes an unknown-author orphan when protectUnknownAuthors is off (explicit narrow path)", () => {
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/projects/legacy.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-05-01T00:00:00.000Z",
-          direction: "down",
-        },
-      },
-    };
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-      callerSub: "sub-corey",
-    });
-    expect(plan.orphans.map((o) => o.path)).toEqual([
-      "companies/indigo/projects/legacy.md",
-    ]);
-  });
-
-  it("ignores authorship when no callerSub is supplied (back-compat)", () => {
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/projects/mine.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-05-01T00:00:00.000Z",
-          direction: "down",
-          createdBySub: "sub-corey",
-        },
-      },
-    };
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-    });
-    expect(plan.orphans.map((o) => o.path)).toEqual([
-      "companies/indigo/projects/mine.md",
-    ]);
-  });
-});
-
-describe("applyScopeShrink", () => {
-  let hqRoot: string;
-
-  beforeEach(() => {
-    hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-scope-shrink-apply-"));
-  });
-
-  afterEach(() => {
-    fs.rmSync(hqRoot, { recursive: true, force: true });
-  });
-
-  it("deletes clean orphans on disk + tombstones their journal entries", () => {
-    const abs = path.join(hqRoot, "companies/indigo/scratch/clean.md");
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, "clean");
-
-    const syncedAt = new Date().toISOString();
-    const past = Date.now() - 60_000;
-    fs.utimesSync(abs, past / 1000, past / 1000);
-
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/scratch/clean.md": {
-          hash: sha256("clean"),
-          size: 5,
-          syncedAt,
-          direction: "down",
-        },
-      },
-    };
-
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-    });
-    const result = applyScopeShrink({
-      journal,
-      plan,
-      hqRoot,
-      forceScopeShrink: false,
-    });
-
-    expect(result.cleanRemoved).toBe(1);
-    expect(result.dirtyTombstoned).toBe(0);
-    expect(fs.existsSync(abs)).toBe(false);
-    expect(
-      journal.files["companies/indigo/scratch/clean.md"]?.removedAt,
-    ).toBeTruthy();
-    expect(
-      journal.files["companies/indigo/scratch/clean.md"]?.removedReason,
-    ).toBe("scope_shrink");
-  });
-
-  it("leaves dirty files on disk when forceScopeShrink: true, but tombstones the entry", () => {
-    const abs = path.join(hqRoot, "companies/indigo/scratch/dirty.md");
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, "MODIFIED");
-
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/scratch/dirty.md": {
-          hash: sha256("ORIGINAL"), // mismatch — dirty
-          size: 8,
-          syncedAt: new Date().toISOString(),
-          direction: "down",
-        },
-      },
-    };
-
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-    });
-    const result = applyScopeShrink({
-      journal,
-      plan,
-      hqRoot,
-      forceScopeShrink: true,
-    });
-
-    expect(result.dirtyTombstoned).toBe(1);
-    expect(fs.existsSync(abs)).toBe(true); // PRESERVED
-    expect(fs.readFileSync(abs, "utf-8")).toBe("MODIFIED");
-    expect(
-      journal.files["companies/indigo/scratch/dirty.md"]?.removedAt,
-    ).toBeTruthy();
-  });
-
-  it("accepts a custom reason for the tombstone (e.g. narrow_apply)", () => {
-    const abs = path.join(hqRoot, "companies/indigo/scratch/clean.md");
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, "x");
-    const past = Date.now() - 60_000;
-    fs.utimesSync(abs, past / 1000, past / 1000);
-
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        "companies/indigo/scratch/clean.md": {
-          hash: sha256("x"),
-          size: 1,
-          syncedAt: new Date().toISOString(),
-          direction: "down",
-        },
-      },
-    };
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-    });
-    applyScopeShrink({
-      journal,
-      plan,
-      hqRoot,
-      forceScopeShrink: false,
-      reason: "narrow_apply",
-    });
-    expect(
-      journal.files["companies/indigo/scratch/clean.md"]?.removedReason,
-    ).toBe("narrow_apply");
-  });
-
-  // DEV-1768 fix #3: clean orphans are MOVED to quarantine (recoverable),
-  // not unlinked, when `cleanDisposition: "quarantine"`.
-  it("quarantines clean orphans (moves, not deletes) and reports named paths", () => {
-    const rel = "companies/indigo/scratch/clean.md";
-    const abs = path.join(hqRoot, rel);
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, "clean");
-    const past = Date.now() - 60_000;
-    fs.utimesSync(abs, past / 1000, past / 1000);
-
-    const quarantineRoot = path.join(hqRoot, ".hq", "scope-quarantine", "indigo");
-    const journal: SyncJournal = {
-      ...emptyJournal(),
-      files: {
-        [rel]: { hash: sha256("clean"), size: 5, syncedAt: new Date().toISOString(), direction: "down" },
-      },
-    };
-    const plan = buildScopeShrinkPlan({
-      journal,
-      hqRoot,
-      lastPrefixSet: ["companies/indigo/"],
-      currentPrefixSet: ["companies/indigo/meetings/"],
-    });
-    const result = applyScopeShrink({
-      journal,
-      plan,
-      hqRoot,
-      forceScopeShrink: false,
-      cleanDisposition: "quarantine",
-      quarantineRoot,
-    });
-
-    expect(result.cleanQuarantined).toBe(1);
-    expect(result.cleanRemoved).toBe(0);
-    expect(result.quarantinedPaths).toEqual([rel]);
-    expect(result.removedPaths).toEqual([]);
-    expect(result.quarantineRoot).toBe(quarantineRoot);
-    // Moved, not deleted: gone from the working tree, present + intact in quarantine.
-    expect(fs.existsSync(abs)).toBe(false);
-    const quarantined = path.join(quarantineRoot, rel);
-    expect(fs.existsSync(quarantined)).toBe(true);
-    expect(fs.readFileSync(quarantined, "utf-8")).toBe("clean");
-    // Journal entry tombstoned so it stops being re-flagged (idempotent).
-    expect(journal.files[rel]?.removedAt).toBeTruthy();
-  });
-});
-
-describe("ScopeShrinkBlockedError", () => {
-  it("carries from/to syncMode + dirty/clean orphan lists for the CLI", () => {
-    const err = new ScopeShrinkBlockedError(
-      "cmp_indigo",
-      "all",
-      "shared",
-      [
-        {
-          path: "companies/indigo/scratch/notes.md",
-          entry: {
-            hash: "h",
-            size: 1,
-            syncedAt: "",
-            direction: "down",
-          },
-          clean: false,
-          dirtyReason: "hash-mismatch",
-        },
-      ],
-      [],
-    );
-    expect(err.code).toBe("SCOPE_SHRINK_BLOCKED");
-    expect(err.fromMode).toBe("all");
-    expect(err.toMode).toBe("shared");
-    expect(err.dirty).toHaveLength(1);
-    expect(err.name).toBe("ScopeShrinkBlockedError");
-  });
-
-  // DEV-1768 fix #2: advice must be FOLLOWABLE from the entry point that throws.
-  // The old message always said "pass --force-scope-shrink", which the menubar
-  // runner cannot accept.
-  const mk = (ctx?: "cli" | "runner" | "engine") =>
-    new ScopeShrinkBlockedError("cmp_x", "all", "shared", [], [], ctx);
-
-  it("runner-context advice points at a terminal command, NOT an impossible flag", () => {
-    const msg = mk("runner").message;
-    // The followable path from the menubar is a terminal command.
-    expect(msg).toContain("hq sync narrow --apply");
-    // It must NOT imply the flag is acceptable to the menubar itself.
-    expect(msg).toContain("menubar sync cannot take this flag");
-  });
-
-  it("cli-context advice offers the flag the CLI actually accepts", () => {
-    const msg = mk("cli").message;
-    expect(msg).toContain("--force-scope-shrink");
-    expect(msg).toContain("hq sync narrow --apply");
-  });
-
-  it("defaults to the engine/library advice when no context is given", () => {
-    expect(mk().adviceContext).toBe("engine");
-    expect(mk().message).toContain("hq sync narrow --apply");
-  });
-});