@usefragments/core 1.11.0 → 2.0.0

package/src/feature-plan/feature-plan-v1.test.ts

@@ -1,529 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { featurePlanIdFromEntropy } from "../domain-ids.js";
-import {
-  agentFeatureContextV1Schema,
-  approvedFeatureManifestV1Schema,
-  buildApprovedFeatureManifestV1,
-  buildFeatureProposalV1,
-  featureProposalV1Schema,
-  parseApprovedFeatureManifestV1,
-  parseFeatureProposalV1,
-  type ApprovedFeatureManifestInputV1,
-  type FeatureProposalInputV1,
-} from "./index.js";
-
-const A = "a".repeat(64);
-const B = "b".repeat(64);
-const C = "c".repeat(64);
-const D = "d".repeat(64);
-const PLAN_ID = featurePlanIdFromEntropy("00112233445566778899aabbccddeeff");
-
-function proposalInput(overrides: Partial<FeatureProposalInputV1> = {}): FeatureProposalInputV1 {
-  return {
-    schemaVersion: 1,
-    kind: "proposal",
-    planId: PLAN_ID,
-    pins: {
-      bindingId: "binding_1",
-      grounding: {
-        sourceCommitId: "head-sha",
-        analysisPlanDigest: A,
-        contextSliceDigest: B,
-      },
-      authority: {
-        fcid: C,
-        contractArtifactDigest: D,
-        analysisObligationsDigest: A,
-      },
-      evidenceDigest: B,
-    },
-    placement: {
-      targetKind: "page",
-      targetRef: "settings/notifications",
-      routeRef: "/settings/notifications",
-      parentSlotRef: "WorkspacePage.content",
-      evidenceRefIds: ["source-shell"],
-    },
-    componentUses: [
-      {
-        useId: "switch",
-        componentId: "Switch",
-        importPath: "@usefragments/ui",
-        purpose: "Toggle notification preference",
-        props: { size: "md", disabled: false },
-        evidenceRefIds: ["contract-switch", "source-form"],
-      },
-    ],
-    tokenUses: [
-      {
-        useId: "section-gap",
-        tokenId: "--fui-space-3",
-        role: "gap",
-        evidenceRefIds: ["contract-space"],
-      },
-    ],
-    patternUses: [
-      {
-        useId: "settings-row",
-        patternId: "cloud.settings-row",
-        patternRevisionDigest: A,
-        status: "approved_guidance",
-        disposition: "reuse",
-        evidenceRefIds: ["source-form"],
-      },
-    ],
-    layout: {
-      concerns: [
-        {
-          concern: "outer_inline_spacing",
-          ownerLayer: "application_shell",
-          ownerRef: "WorkspacePage",
-          childAction: "consume",
-          evidenceRefIds: ["source-shell"],
-        },
-        {
-          concern: "child_gap",
-          ownerLayer: "section",
-          ownerRef: "NotificationPreferencesSection",
-          childAction: "own",
-          tokenRef: "--fui-space-3",
-          evidenceRefIds: ["contract-space"],
-        },
-      ],
-    },
-    responsive: [
-      {
-        decisionId: "responsive-row",
-        source: "observed",
-        breakpointRef: "$fui-breakpoint-md",
-        behavior: "Stack label and control below md",
-        evidenceRefIds: ["source-form"],
-      },
-    ],
-    scenarios: [
-      {
-        scenarioId: "save-error",
-        viewportRef: "mobile",
-        dataState: "error",
-        interactionState: "saving",
-        acceptanceIds: ["A2"],
-      },
-    ],
-    gaps: [
-      {
-        gapId: "inline-field",
-        capability: "Inline labelled boolean field",
-        required: false,
-        disposition: "local_composition",
-        reason: "Reuse the existing settings-row composition",
-        evidenceRefIds: ["source-form"],
-      },
-    ],
-    acceptance: [
-      {
-        acceptanceId: "A1",
-        statement: "Owner saves a preference and reload sees it",
-        proof: "integration",
-        required: true,
-        evidenceRefIds: ["user-intent"],
-      },
-      {
-        acceptanceId: "A2",
-        statement: "A failed save restores the prior value",
-        proof: "browser",
-        required: true,
-        evidenceRefIds: ["user-intent"],
-      },
-    ],
-    questions: [
-      {
-        decisionId: "save-model",
-        kind: "reuse",
-        question: "Save immediately or as a section?",
-        options: [
-          { optionId: "immediate", label: "Immediately", consequence: "Matches current settings" },
-          { optionId: "section", label: "Save section", consequence: "Adds dirty state" },
-        ],
-        recommendedOptionId: "immediate",
-        required: true,
-        evidenceRefIds: ["source-form"],
-      },
-    ],
-    evidenceRefs: [
-      {
-        evidenceId: "user-intent",
-        kind: "user_intent",
-        authority: "user_asserted",
-        ref: "intent:settings-notifications",
-        digest: A,
-      },
-      {
-        evidenceId: "source-shell",
-        kind: "source",
-        authority: "source_observed",
-        ref: "apps/cloud/src/WorkspacePage.tsx:1",
-        digest: B,
-      },
-      {
-        evidenceId: "source-form",
-        kind: "source",
-        authority: "source_observed",
-        ref: "apps/cloud/src/SettingsRow.tsx:1",
-        digest: C,
-      },
-      {
-        evidenceId: "contract-switch",
-        kind: "contract",
-        authority: "contract_approved",
-        ref: "component:Switch",
-        digest: D,
-      },
-      {
-        evidenceId: "contract-space",
-        kind: "contract",
-        authority: "contract_approved",
-        ref: "token:--fui-space-3",
-        digest: A,
-      },
-    ],
-    ...overrides,
-  };
-}
-
-function manifestInput(
-  overrides: Partial<ApprovedFeatureManifestInputV1> = {}
-): ApprovedFeatureManifestInputV1 {
-  const proposal = buildFeatureProposalV1(proposalInput());
-  return {
-    schemaVersion: 1,
-    kind: "approved_manifest",
-    planId: proposal.planId,
-    parentRevisionDigest: proposal.revisionDigest,
-    proposalRevisionDigest: proposal.revisionDigest,
-    pins: proposal.pins,
-    validatedGrounding: { ...proposal.pins.grounding },
-    placement: proposal.placement,
-    componentUses: proposal.componentUses,
-    tokenUses: proposal.tokenUses,
-    patternUses: proposal.patternUses,
-    layout: proposal.layout,
-    responsive: proposal.responsive,
-    scenarios: proposal.scenarios,
-    gaps: proposal.gaps,
-    acceptance: proposal.acceptance,
-    evidenceRefs: proposal.evidenceRefs,
-    decisions: [{ decisionId: "save-model", selectedOptionId: "immediate" }],
-    approval: {
-      approverUserId: "user_1",
-      decisionDigest: D,
-      approvedAt: "2026-09-01T12:00:00.000Z",
-    },
-    ...overrides,
-  };
-}
-
-describe("FeatureProposalV1", () => {
-  it("has a checked-in stable revision digest", () => {
-    const proposal = buildFeatureProposalV1(proposalInput());
-    expect(proposal.revisionDigest).toBe(
-      "a0e17ecec3c2a88ed421bd1102c1a806be34887f8e053b7236cd5e9551fd0cf7"
-    );
-    expect(proposal.revisionId).toBe(`fpr_${proposal.revisionDigest}`);
-    expect(parseFeatureProposalV1(proposal)).toEqual(proposal);
-  });
-
-  it("normalizes set-like order but preserves decision-option order", () => {
-    const first = buildFeatureProposalV1(proposalInput());
-    const reordered = buildFeatureProposalV1(
-      proposalInput({
-        evidenceRefs: [...proposalInput().evidenceRefs].reverse(),
-        componentUses: proposalInput().componentUses.map((use) => ({
-          ...use,
-          evidenceRefIds: [...use.evidenceRefIds].reverse(),
-          props: { disabled: false, size: "md" },
-        })),
-        acceptance: [...proposalInput().acceptance].reverse(),
-        layout: { concerns: [...proposalInput().layout.concerns].reverse() },
-      })
-    );
-    expect(reordered.revisionDigest).toBe(first.revisionDigest);
-
-    const optionsReordered = buildFeatureProposalV1(
-      proposalInput({
-        questions: proposalInput().questions.map((question) => ({
-          ...question,
-          options: [...question.options].reverse(),
-        })),
-      })
-    );
-    expect(optionsReordered.revisionDigest).not.toBe(first.revisionDigest);
-  });
-
-  it("uses locale-independent Unicode ordering for canonical feature records", () => {
-    const unicodeEvidence = [
-      {
-        evidenceId: "unicode-ä",
-        kind: "source" as const,
-        authority: "source_observed" as const,
-        ref: "src/ä.tsx:1",
-        digest: A,
-      },
-      {
-        evidenceId: "unicode-z",
-        kind: "source" as const,
-        authority: "source_observed" as const,
-        ref: "src/z.tsx:1",
-        digest: B,
-      },
-    ];
-    const first = buildFeatureProposalV1(
-      proposalInput({ evidenceRefs: [...proposalInput().evidenceRefs, ...unicodeEvidence] })
-    );
-    const reordered = buildFeatureProposalV1(
-      proposalInput({
-        evidenceRefs: [...proposalInput().evidenceRefs, ...unicodeEvidence].reverse(),
-      })
-    );
-    expect(
-      first.evidenceRefs
-        .map((evidence) => evidence.evidenceId)
-        .filter((evidenceId) => evidenceId.startsWith("unicode-"))
-    ).toEqual(["unicode-z", "unicode-ä"]);
-    expect(reordered.revisionDigest).toBe(first.revisionDigest);
-  });
-
-  it("changes identity for authority, layout, and workflow changes", () => {
-    const first = buildFeatureProposalV1(proposalInput());
-    expect(
-      buildFeatureProposalV1(
-        proposalInput({ pins: { ...proposalInput().pins, evidenceDigest: C } })
-      ).revisionDigest
-    ).not.toBe(first.revisionDigest);
-    expect(
-      buildFeatureProposalV1(
-        proposalInput({
-          layout: {
-            concerns: proposalInput().layout.concerns.map((row) =>
-              row.concern === "child_gap"
-                ? { ...row, ownerLayer: "pattern" as const, ownerRef: "cloud.settings-row" }
-                : row
-            ),
-          },
-        })
-      ).revisionDigest
-    ).not.toBe(first.revisionDigest);
-    expect(
-      buildFeatureProposalV1(
-        proposalInput({ planId: featurePlanIdFromEntropy("ffeeddccbbaa99887766554433221100") })
-      ).revisionDigest
-    ).not.toBe(first.revisionDigest);
-  });
-
-  it("rejects unknown fields, dangling evidence, invalid gaps, and duplicate layout owners", () => {
-    expect(() =>
-      featureProposalV1Schema.parse({ ...buildFeatureProposalV1(proposalInput()), extra: true })
-    ).toThrow();
-    expect(() =>
-      buildFeatureProposalV1(
-        proposalInput({ placement: { ...proposalInput().placement, evidenceRefIds: ["missing"] } })
-      )
-    ).toThrow();
-    expect(() =>
-      buildFeatureProposalV1(
-        proposalInput({
-          componentUses: [
-            {
-              ...proposalInput().componentUses[0],
-              props: { label: "x".repeat(33 * 1024) },
-            },
-          ],
-        })
-      )
-    ).toThrow();
-    expect(() =>
-      buildFeatureProposalV1(
-        proposalInput({
-          gaps: [{ ...proposalInput().gaps[0], disposition: "invent" as never }],
-        })
-      )
-    ).toThrow();
-    expect(() =>
-      buildFeatureProposalV1(
-        proposalInput({
-          layout: {
-            concerns: [
-              ...proposalInput().layout.concerns,
-              { ...proposalInput().layout.concerns[0], ownerRef: "FeaturePage" },
-            ],
-          },
-        })
-      )
-    ).toThrow();
-  });
-});
-
-describe("ApprovedFeatureManifestV1", () => {
-  it("pins approved choices and excludes approvedAt from semantic identity", () => {
-    const manifest = buildApprovedFeatureManifestV1(manifestInput());
-    expect(manifest.revisionDigest).toBe(
-      "2b9eb1d40d853cd47412d811526eaaba6aaaa7cb855778d08fa1d4acd930bcaa"
-    );
-    expect(parseApprovedFeatureManifestV1(manifest)).toEqual(manifest);
-    const laterTimestamp = buildApprovedFeatureManifestV1(
-      manifestInput({
-        approval: { ...manifestInput().approval, approvedAt: "2026-09-02T12:00:00.000Z" },
-      })
-    );
-    expect(laterTimestamp.revisionDigest).toBe(manifest.revisionDigest);
-    const differentChoice = buildApprovedFeatureManifestV1(
-      manifestInput({ decisions: [{ decisionId: "save-model", selectedOptionId: "section" }] })
-    );
-    expect(differentChoice.revisionDigest).not.toBe(manifest.revisionDigest);
-  });
-
-  it("blocks required unresolved/proposed gaps and dangling override decisions", () => {
-    expect(() =>
-      buildApprovedFeatureManifestV1(
-        manifestInput({
-          gaps: [
-            {
-              ...manifestInput().gaps[0],
-              required: true,
-              disposition: "unresolved",
-            },
-          ],
-        })
-      )
-    ).toThrow();
-    expect(() =>
-      buildApprovedFeatureManifestV1(
-        manifestInput({
-          gaps: [
-            {
-              ...manifestInput().gaps[0],
-              required: true,
-              disposition: "proposed_contract_addition",
-              proposedContractCandidateId: "candidate-field-row",
-            },
-          ],
-        })
-      )
-    ).toThrow();
-    expect(() =>
-      buildApprovedFeatureManifestV1(
-        manifestInput({
-          layout: {
-            concerns: manifestInput().layout.concerns.map((row) =>
-              row.concern === "child_gap"
-                ? { ...row, childAction: "override" as const, overrideDecisionId: "missing" }
-                : row
-            ),
-          },
-        })
-      )
-    ).toThrow();
-  });
-
-  it("allows compatible re-grounding to a newer source and exact analysis plan", () => {
-    const advanced = buildApprovedFeatureManifestV1(
-      manifestInput({
-        validatedGrounding: {
-          sourceCommitId: "next-head-sha",
-          analysisPlanDigest: C,
-          contextSliceDigest: manifestInput().pins.grounding.contextSliceDigest,
-        },
-      })
-    );
-    expect(advanced.validatedGrounding).toMatchObject({
-      sourceCommitId: "next-head-sha",
-      analysisPlanDigest: C,
-    });
-    expect(() =>
-      buildApprovedFeatureManifestV1(
-        manifestInput({
-          validatedGrounding: {
-            ...manifestInput().validatedGrounding,
-            contextSliceDigest: D,
-          },
-        })
-      )
-    ).toThrow(/material context/u);
-  });
-
-  it.each(["observed", "candidate", "deprecated"] as const)(
-    "prevents a %s pattern from becoming an approved reusable claim",
-    (status) => {
-      expect(() =>
-        buildApprovedFeatureManifestV1(
-          manifestInput({
-            patternUses: [
-              {
-                ...manifestInput().patternUses[0],
-                status,
-                disposition: "reuse",
-              },
-            ],
-          })
-        )
-      ).toThrow(/may be reused/u);
-    }
-  );
-
-  it.each(["approved_guidance", "contract_canonical"] as const)(
-    "allows a %s pattern to be reused",
-    (status) => {
-      expect(
-        buildApprovedFeatureManifestV1(
-          manifestInput({
-            patternUses: [{ ...manifestInput().patternUses[0], status, disposition: "reuse" }],
-          })
-        ).patternUses[0]
-      ).toMatchObject({ status, disposition: "reuse" });
-    }
-  );
-
-  it("validates the bounded agent projection", () => {
-    const manifest = buildApprovedFeatureManifestV1(manifestInput());
-    const context = {
-      schemaVersion: 1 as const,
-      planId: manifest.planId,
-      manifestDigest: manifest.revisionDigest,
-      pins: manifest.pins,
-      validatedGrounding: manifest.validatedGrounding,
-      target: manifest.placement,
-      componentUses: manifest.componentUses,
-      tokenUses: manifest.tokenUses,
-      patternUses: manifest.patternUses,
-      layout: manifest.layout,
-      responsive: manifest.responsive,
-      scenarios: manifest.scenarios,
-      acceptedGaps: manifest.gaps,
-      acceptance: manifest.acceptance,
-      decisions: manifest.decisions,
-      relevantFiles: ["apps/cloud/src/settings.tsx"],
-      commands: ["pnpm test"],
-    };
-    expect(agentFeatureContextV1Schema.parse(context)).toEqual(context);
-    expect(() =>
-      agentFeatureContextV1Schema.parse({
-        ...context,
-        commands: ["x".repeat(70 * 1024)],
-      })
-    ).toThrow();
-    expect(() =>
-      agentFeatureContextV1Schema.parse({
-        ...context,
-        relevantFiles: ["/tmp/customer-source.tsx"],
-      })
-    ).toThrow();
-  });
-
-  it("keeps the stored manifest validator strict", () => {
-    expect(() =>
-      approvedFeatureManifestV1Schema.parse({
-        ...buildApprovedFeatureManifestV1(manifestInput()),
-        actorEmail: "not-in-authority-record@example.com",
-      })
-    ).toThrow();
-  });
-});

package/src/feature-plan/index.ts

@@ -1,65 +0,0 @@
-export {
-  AGENT_FEATURE_CONTEXT_MAX_BYTES_V1,
-  FEATURE_PLAN_MAX_ACCEPTANCE_ITEMS_V1,
-  FEATURE_PLAN_MAX_DECISIONS_V1,
-  FEATURE_PLAN_MAX_EVIDENCE_REFS_V1,
-  FEATURE_PLAN_MAX_GAPS_V1,
-  FEATURE_PLAN_MAX_SCENARIOS_V1,
-  FEATURE_PLAN_MAX_TEXT_BYTES_V1,
-  FEATURE_PLAN_MAX_USES_PER_KIND_V1,
-  approvedFeatureManifestInputV1Schema,
-  approvedFeatureManifestV1Schema,
-  capabilityGapV1Schema,
-  componentUseDecisionV1Schema,
-  decisionRequestV1Schema,
-  decisionResolutionV1Schema,
-  evidenceRefV1Schema,
-  featureAcceptanceItemV1Schema,
-  featurePinsV1Schema,
-  featureProposalInputV1Schema,
-  featureProposalV1Schema,
-  gapDispositionV1Schema,
-  layoutConcernV1Schema,
-  layoutOwnershipV1Schema,
-  patternStatusV1Schema,
-  patternUseDecisionV1Schema,
-  placementDecisionV1Schema,
-  responsiveDecisionV1Schema,
-  scenarioRequirementV1Schema,
-  tokenUseDecisionV1Schema,
-} from "./types.js";
-export type {
-  AgentFeatureContextV1,
-  ApprovedFeatureManifestInputV1,
-  ApprovedFeatureManifestV1,
-  CapabilityGapV1,
-  ComponentUseDecisionV1,
-  DecisionRequestV1,
-  DecisionResolutionV1,
-  EvidenceRefV1,
-  FeatureAcceptanceItemV1,
-  FeaturePinsV1,
-  FeatureProposalInputV1,
-  FeatureProposalV1,
-  GapDispositionV1,
-  LayoutConcernV1,
-  LayoutOwnershipV1,
-  PatternStatusV1,
-  PatternUseDecisionV1,
-  PlacementDecisionV1,
-  ResponsiveDecisionV1,
-  ScenarioRequirementV1,
-  TokenUseDecisionV1,
-} from "./types.js";
-export {
-  agentFeatureContextV1Schema,
-  approvedFeatureManifestRevisionDigestV1,
-  buildApprovedFeatureManifestV1,
-  buildFeatureProposalV1,
-  featureProposalRevisionDigestV1,
-  normalizeApprovedFeatureManifestInputV1,
-  normalizeFeatureProposalInputV1,
-  parseAgentFeatureContextV1,
-  parseApprovedFeatureManifestV1,
-  parseFeatureProposalV1,
-} from "./digest.js";