@usefragments/core 1.10.2 → 2.0.0

package/src/analysis-plan/types.ts

@@ -0,0 +1,207 @@
+import { z } from "zod";
+import {
+  analysisPlanIdStringSchema,
+  digestHexStringSchema,
+  type AnalysisPlanId,
+  type DigestHex,
+} from "../domain-ids.js";
+import {
+  repositoryBindingKeyV1Schema,
+  type RepositoryBindingKeyV1,
+} from "../repository-binding.js";
+
+export const ANALYSIS_PLAN_MAX_REGIONS_V1 = 1_000;
+export const ANALYSIS_PLAN_MAX_CAPABILITIES_V1 = 256;
+export const ANALYSIS_PLAN_MAX_DIALECTS_PER_REGION_V1 = 64;
+
+export const ANALYSIS_LIMIT_CEILINGS_V1 = {
+  maxSourceFiles: 100_000,
+  maxSourceBytes: 1_073_741_824,
+  maxFileBytes: 10_485_760,
+  maxFacts: 1_000_000,
+  maxRegions: ANALYSIS_PLAN_MAX_REGIONS_V1,
+  maxDiagnostics: 100_000,
+  maxDurationMs: 900_000,
+} as const;
+
+const bounded = (max: number) => z.string().min(1).max(max);
+const positiveBoundedInteger = (max: number) => z.number().int().positive().max(max);
+const uniqueStrings = (values: readonly string[]): boolean =>
+  new Set(values).size === values.length;
+
+export const coverageStateV1Schema = z.enum([
+  "analyzed",
+  "unsupported",
+  "excluded_by_contract",
+  "skipped_limit",
+  "failed",
+]);
+export type CoverageStateV1 = z.infer<typeof coverageStateV1Schema>;
+
+export const analysisLimitsV1Schema = z
+  .object({
+    maxSourceFiles: positiveBoundedInteger(ANALYSIS_LIMIT_CEILINGS_V1.maxSourceFiles),
+    maxSourceBytes: positiveBoundedInteger(ANALYSIS_LIMIT_CEILINGS_V1.maxSourceBytes),
+    maxFileBytes: positiveBoundedInteger(ANALYSIS_LIMIT_CEILINGS_V1.maxFileBytes),
+    maxFacts: positiveBoundedInteger(ANALYSIS_LIMIT_CEILINGS_V1.maxFacts),
+    maxRegions: positiveBoundedInteger(ANALYSIS_LIMIT_CEILINGS_V1.maxRegions),
+    maxDiagnostics: positiveBoundedInteger(ANALYSIS_LIMIT_CEILINGS_V1.maxDiagnostics),
+    maxDurationMs: positiveBoundedInteger(ANALYSIS_LIMIT_CEILINGS_V1.maxDurationMs),
+  })
+  .strict();
+export type AnalysisLimitsV1 = z.infer<typeof analysisLimitsV1Schema>;
+
+export const analysisRegionV1Schema = z
+  .object({
+    regionId: bounded(256),
+    pathPattern: bounded(4_096),
+    kind: z.enum(["component_source", "style_source", "token_source", "config"]),
+    language: bounded(64),
+    required: z.boolean(),
+    requiredDialects: z
+      .array(bounded(128))
+      .max(ANALYSIS_PLAN_MAX_DIALECTS_PER_REGION_V1)
+      .refine(uniqueStrings, "requiredDialects must be unique"),
+    analyzer: z
+      .object({
+        id: bounded(256),
+        interfaceVersion: bounded(128),
+        implementationVersion: bounded(128),
+      })
+      .strict(),
+  })
+  .strict();
+export type AnalysisRegionV1 = z.infer<typeof analysisRegionV1Schema>;
+
+export const coverageRegionV1Schema = z
+  .object({
+    regionId: bounded(256),
+    state: coverageStateV1Schema,
+    fileCount: z.number().int().nonnegative().max(ANALYSIS_LIMIT_CEILINGS_V1.maxSourceFiles),
+    byteCount: z.number().int().nonnegative().max(ANALYSIS_LIMIT_CEILINGS_V1.maxSourceBytes),
+    diagnosticIds: z
+      .array(bounded(256))
+      .max(ANALYSIS_LIMIT_CEILINGS_V1.maxDiagnostics)
+      .refine(uniqueStrings, "diagnosticIds must be unique"),
+  })
+  .strict();
+export type CoverageRegionV1 = z.infer<typeof coverageRegionV1Schema>;
+
+const coverageCountsV1Schema = z
+  .object({
+    analyzed: z.number().int().nonnegative(),
+    unsupported: z.number().int().nonnegative(),
+    excluded_by_contract: z.number().int().nonnegative(),
+    skipped_limit: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+  })
+  .strict();
+
+export const coverageSummaryV1Schema = z
+  .object({
+    plannedRegions: z.number().int().nonnegative(),
+    observedRegions: z.number().int().nonnegative(),
+    requiredRegions: z.number().int().nonnegative(),
+    requiredByState: coverageCountsV1Schema,
+    optionalByState: coverageCountsV1Schema,
+    eligibleFiles: z.number().int().nonnegative(),
+    analyzedFiles: z.number().int().nonnegative(),
+    analyzedBytes: z.number().int().nonnegative(),
+  })
+  .strict();
+export type CoverageSummaryV1 = z.infer<typeof coverageSummaryV1Schema>;
+
+const analysisPlanBaseShape = {
+  binding: repositoryBindingKeyV1Schema,
+  source: z
+    .object({
+      commitId: bounded(256),
+      treeId: bounded(256).optional(),
+      defaultBranch: bounded(256),
+      acquiredBy: z.enum(["github_app", "local_worktree", "ci_attested"]),
+    })
+    .strict(),
+  contract: z
+    .object({
+      fcid: digestHexStringSchema,
+      artifactDigest: digestHexStringSchema,
+    })
+    .strict(),
+  config: z
+    .object({
+      path: bounded(4_096).refine(
+        (value) =>
+          !value.startsWith("/") && !value.includes("\\") && !value.split("/").includes(".."),
+        "config path must be a portable repository-relative path"
+      ),
+      digest: digestHexStringSchema,
+    })
+    .strict(),
+  profile: z
+    .object({
+      id: z.literal("react-web-v1"),
+      version: bounded(128),
+      capabilities: z
+        .array(bounded(128))
+        .max(ANALYSIS_PLAN_MAX_CAPABILITIES_V1)
+        .refine(uniqueStrings, "capabilities must be unique"),
+    })
+    .strict(),
+  regions: z
+    .array(analysisRegionV1Schema)
+    .max(ANALYSIS_PLAN_MAX_REGIONS_V1)
+    .refine(
+      (regions) => new Set(regions.map((region) => region.regionId)).size === regions.length,
+      "regionId values must be unique"
+    ),
+  limits: analysisLimitsV1Schema,
+  evaluatorVersion: bounded(128),
+  createdAt: z.string().datetime({ offset: true }),
+};
+
+function validatePlanLimits(
+  plan: { regions: readonly AnalysisRegionV1[]; limits: AnalysisLimitsV1 },
+  context: z.RefinementCtx
+): void {
+  if (plan.regions.length > plan.limits.maxRegions) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["regions"],
+      message: "Planned regions exceed the plan's maxRegions limit",
+    });
+  }
+  if (plan.limits.maxFileBytes > plan.limits.maxSourceBytes) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["limits", "maxFileBytes"],
+      message: "maxFileBytes cannot exceed maxSourceBytes",
+    });
+  }
+}
+
+export const analysisPlanInputV1Schema = z
+  .object(analysisPlanBaseShape)
+  .strict()
+  .superRefine(validatePlanLimits);
+export type AnalysisPlanInputV1 = z.input<typeof analysisPlanInputV1Schema>;
+
+export const analysisPlanV1Schema = z
+  .object({
+    schemaVersion: z.literal(1),
+    analysisPlanId: analysisPlanIdStringSchema,
+    ...analysisPlanBaseShape,
+    obligationsDigest: digestHexStringSchema,
+    digest: digestHexStringSchema,
+  })
+  .strict()
+  .superRefine(validatePlanLimits);
+
+export interface AnalysisPlanV1 extends Omit<
+  z.output<typeof analysisPlanV1Schema>,
+  "analysisPlanId" | "digest" | "obligationsDigest"
+> {
+  analysisPlanId: AnalysisPlanId;
+  binding: RepositoryBindingKeyV1;
+  obligationsDigest: DigestHex;
+  digest: DigestHex;
+}

package/src/approved-contract-tokens.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import {
+  APPROVED_CONTRACT_TOKEN_MAX_NAMES,
+  APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH,
+  isApprovedContractTokenNames,
+} from "./approved-contract-tokens.js";
+import { parseComponentGovernancePolicyJson } from "./governance.js";
+
+describe("approved token transport", () => {
+  it("distinguishes absent authority from an explicitly empty vocabulary", () => {
+    expect(isApprovedContractTokenNames(undefined)).toBe(false);
+    expect(isApprovedContractTokenNames(null)).toBe(false);
+    expect(isApprovedContractTokenNames([])).toBe(true);
+    expect(isApprovedContractTokenNames(["--approved"])).toBe(true);
+  });
+  it("enforces the same bounded vocabulary on every consumer", () => {
+    expect(isApprovedContractTokenNames(Array(APPROVED_CONTRACT_TOKEN_MAX_NAMES).fill("--x"))).toBe(
+      true
+    );
+    expect(
+      isApprovedContractTokenNames(Array(APPROVED_CONTRACT_TOKEN_MAX_NAMES + 1).fill("--x"))
+    ).toBe(false);
+    expect(
+      isApprovedContractTokenNames(["--" + "x".repeat(APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH - 2)])
+    ).toBe(true);
+    expect(
+      isApprovedContractTokenNames(["--" + "x".repeat(APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH - 1)])
+    ).toBe(false);
+    expect(isApprovedContractTokenNames(["--"])).toBe(false);
+    expect(isApprovedContractTokenNames(["local-token"])).toBe(false);
+  });
+});
+
+it("normalizes supported policy envelopes without treating malformed authority as empty rules", () => {
+  for (const payload of ["[]", '{"governance":[]}', '{"rules":[]}'])
+    expect(parseComponentGovernancePolicyJson(payload)).toEqual([]);
+  for (const payload of ["null", "{}", "[{}]", "invalid", '{"governance":false}'])
+    expect(parseComponentGovernancePolicyJson(payload)).toBeNull();
+});

package/src/approved-contract-tokens.ts

@@ -0,0 +1,18 @@
+/** Portable bounds shared by contract authoring and first-party policy clients. */
+export const APPROVED_CONTRACT_TOKEN_MAX_NAMES = 10_000;
+export const APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH = 512;
+
+/** Empty is authored absence; missing is unavailable authority. */
+export function isApprovedContractTokenNames(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length <= APPROVED_CONTRACT_TOKEN_MAX_NAMES &&
+    value.every(
+      (name) =>
+        typeof name === "string" &&
+        name.startsWith("--") &&
+        name.length > 2 &&
+        name.length <= APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH
+    )
+  );
+}

package/src/codes/__tests__/codes.test.ts

@@ -24,6 +24,19 @@ const SUBSYSTEM_EMITTED_CODES = [
   // sources are read before any rule runs, and an unreadable one aborts the
   // scan rather than producing a finding.
   "FUI9009",
+  // Emitted by the compiler, not the rule engine: a `.fragment` source whose
+  // definition fails Core's schema, or whose authored claims contradict the
+  // extracted component, is refused before any rule has a contract to run on.
+  "FUI9010",
+  "FUI9011",
+  // Emitted by Cloud's machine contract write path (CLI route + MCP tool) when
+  // the workspace plan does not include contract writes from machines; the CLI
+  // relays it. Not a rule.
+  "FUI9012",
+  // Emitted by tokens/css-vars-must-be-defined when the rule is active but the
+  // resolved contract vocabulary is empty — a config-level inert diagnostic,
+  // not a second rule id in RULES.
+  "FUI2018",
 ] as const;
 
 const RESERVED_CODES = {

package/src/codes/codes.ts

@@ -273,6 +273,16 @@ export const CODES = [
     lifecycle: "experimental",
     evidenceRequired: true,
   }),
+  code({
+    code: "FUI2018",
+    ruleId: "config/empty-token-vocabulary",
+    category: "system",
+    defaultSeverity: "serious",
+    title: "Token sources resolved to 0 tokens",
+    lifecycle: "experimental",
+    fixAvailable: false,
+    evidenceRequired: true,
+  }),
   ruleCode({
     code: "FUI3001",
     ruleId: "a11y/required-accessible-name",
@@ -527,6 +537,36 @@ export const CODES = [
     fixAvailable: false,
     evidenceRequired: false,
   }),
+  code({
+    code: "FUI9010",
+    ruleId: "fragment/invalid-definition",
+    category: "system",
+    defaultSeverity: "critical",
+    title: "Fragment definition is not valid",
+    lifecycle: "experimental",
+    fixAvailable: false,
+    evidenceRequired: false,
+  }),
+  code({
+    code: "FUI9011",
+    ruleId: "fragment/source-drift",
+    category: "system",
+    defaultSeverity: "critical",
+    title: "Fragment definition drifted from its component source",
+    lifecycle: "experimental",
+    fixAvailable: false,
+    evidenceRequired: false,
+  }),
+  code({
+    code: "FUI9012",
+    ruleId: "contract/write-not-entitled",
+    category: "system",
+    defaultSeverity: "critical",
+    title: "Contract write requires a paid workspace",
+    lifecycle: "experimental",
+    fixAvailable: false,
+    evidenceRequired: false,
+  }),
 ] as const satisfies readonly FuiCode[];
 
 export const byCode: ReadonlyMap<string, FuiCode> = new Map(