@usefragments/core 1.7.0 → 1.8.0

package/dist/schemas/index.d.ts

@@ -1,3 +1,3 @@
 import 'zod';
 export { LegacySeverityLevel, Severity, SeverityLevel, legacySeverityLevelSchema, severityLevelSchema, severitySchema } from '../severity.js';
-export { b as AGENT_FORMAT_SCHEMA_VERSION, c as AgentErrorEnvelope, A as AgentFormat, d as AgentOutput, Q as FactEvidence, R as FactLocation, F as Finding, a as FindingFix, f as FindingReplaceClassTokenFix, g as FindingReplaceComponentFix, h as FindingReplaceImportFix, i as FindingReplacePropValueFix, j as FindingReplaceStyleValueFix, k as Fix, G as GovernanceVerdict, l as GovernanceVerdictMetadata, S as SuppressionDirective, V as ValidatorResult, n as Violation, o as agentErrorEnvelopeSchema, T as agentFindingSchema, p as agentFormatSchema, q as agentIntegritySchema, r as agentOutputSchema, U as agentPlanSchema, t as factEvidenceSchema, u as factLocationSchema, v as findingFixSchema, w as findingReplaceClassTokenFixSchema, x as findingReplaceComponentFixSchema, y as findingReplaceImportFixSchema, z as findingReplacePropValueFixSchema, B as findingReplaceStyleValueFixSchema, C as findingSchema, D as fixSchema, H as governanceVerdictMetadataSchema, J as governanceVerdictSchema, K as normalizeFinding, L as normalizeSeverity, M as normalizeViolation, N as suppressionDirectiveSchema, O as validatorResultSchema, P as violationSchema } from '../index-hZAlYCli.js';
+export { b as AGENT_FORMAT_SCHEMA_VERSION, c as AgentErrorEnvelope, A as AgentFormat, d as AgentOutput, Q as FactEvidence, R as FactLocation, F as Finding, a as FindingFix, f as FindingReplaceClassTokenFix, g as FindingReplaceComponentFix, h as FindingReplaceImportFix, i as FindingReplacePropValueFix, j as FindingReplaceStyleValueFix, k as Fix, G as GovernanceVerdict, l as GovernanceVerdictMetadata, S as SuppressionDirective, V as ValidatorResult, n as Violation, o as agentErrorEnvelopeSchema, T as agentFindingSchema, p as agentFormatSchema, q as agentIntegritySchema, r as agentOutputSchema, U as agentPlanSchema, t as factEvidenceSchema, u as factLocationSchema, v as findingFixSchema, w as findingReplaceClassTokenFixSchema, x as findingReplaceComponentFixSchema, y as findingReplaceImportFixSchema, z as findingReplacePropValueFixSchema, B as findingReplaceStyleValueFixSchema, C as findingSchema, D as fixSchema, H as governanceVerdictMetadataSchema, J as governanceVerdictSchema, K as normalizeFinding, L as normalizeSeverity, M as normalizeViolation, N as suppressionDirectiveSchema, O as validatorResultSchema, P as violationSchema } from '../index-Cxk3SOQP.js';

package/dist/schemas/index.js

@@ -24,7 +24,9 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "../chunk-ZHS52OT4.js";
+} from "../chunk-UUREQ4HD.js";
+import "../chunk-JNBFJ34I.js";
+import "../chunk-EIYNNS77.js";
 import {
   legacySeverityLevelSchema,
   severityLevelSchema,

package/dist/test-utils.d.ts

@@ -1,4 +1,4 @@
-import { C as CompiledBlock, b as CompiledFragment } from './governance-D9KtH-vg.js';
+import { C as CompiledBlock, b as CompiledFragment } from './governance-eEzCyfes.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/core",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "license": "MIT",
   "description": "Core types, schemas, and runtime API for Fragments component definitions",
   "author": "Conan McNicholl",
@@ -64,6 +64,10 @@
       "types": "./dist/package-identity.d.ts",
       "import": "./dist/package-identity.js"
     },
+    "./governance-telemetry": {
+      "types": "./dist/governance-telemetry.d.ts",
+      "import": "./dist/governance-telemetry.js"
+    },
     "./test-utils": {
       "types": "./dist/test-utils.d.ts",
       "import": "./dist/test-utils.js"

package/src/component-contract.ts

@@ -25,6 +25,13 @@ export interface ComponentContract {
   /** Framework hint (for extraction and documentation) */
   framework?: 'react' | 'vue' | 'svelte' | 'web-components' | 'angular';
 
+  /** External npm packages required by this component (displayed in docs Setup section) */
+  dependencies?: Array<{
+    name: string;
+    version: string;
+    reason?: string;
+  }>;
+
   /** Path to the component source file, relative to fragments.config.ts root */
   sourcePath: string;
 
@@ -215,6 +222,11 @@ export const componentContractSchema = z.object({
   tags: z.array(z.string()).optional(),
   status: z.enum(['stable', 'beta', 'deprecated', 'experimental']).optional(),
   framework: z.enum(['react', 'vue', 'svelte', 'web-components', 'angular']).optional(),
+  dependencies: z.array(z.object({
+    name: z.string(),
+    version: z.string(),
+    reason: z.string().optional(),
+  })).optional(),
   sourcePath: z.string(),
   exportName: z.string(),
   propsSummary: z.array(z.string()),

package/src/contract-parser.ts

@@ -21,6 +21,7 @@ export interface CompiledContractOutput {
     category: string;
     tags?: string[];
     status?: 'stable' | 'beta' | 'deprecated' | 'experimental';
+    dependencies?: Array<{ name: string; version: string; reason?: string }>;
     figma?: string;
     figmaProps?: Record<string, unknown>;
   };
@@ -112,6 +113,7 @@ export function parseComponentContract(
       category: validated.category,
       tags: validated.tags,
       status: validated.status,
+      dependencies: validated.dependencies,
       figma: validated.figma?.nodeUrl,
       figmaProps: validated.figma?.propMappings as Record<string, unknown> | undefined,
     },

package/src/governance-telemetry.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import {
+  GOVERNANCE_TELEMETRY_FIELDS,
+  GOVERNANCE_TELEMETRY_TOP_LEVEL_FIELDS,
+} from "./governance-telemetry.js";
+
+describe("governance telemetry disclosure", () => {
+  it("covers every declared top-level wire field", () => {
+    expect(
+      [...new Set(GOVERNANCE_TELEMETRY_FIELDS.map((field) => field.topLevelField))].sort()
+    ).toEqual([...GOVERNANCE_TELEMETRY_TOP_LEVEL_FIELDS].sort());
+  });
+
+  it("keeps field-family paths unique", () => {
+    const paths = GOVERNANCE_TELEMETRY_FIELDS.map((field) => field.path);
+    expect(new Set(paths).size).toBe(paths.length);
+  });
+});

package/src/governance-telemetry.ts

@@ -0,0 +1,398 @@
+/**
+ * Public disclosure contract for `fragments-governance-report:v1`.
+ *
+ * Brace groups enumerate closed sibling fields without hiding additions behind
+ * `*`. The three named placeholder fields are the only intentionally open
+ * records: configured ignore reasons, configured categories, and rule-specific
+ * evidence facts.
+ */
+export type GovernanceTelemetryCarriage =
+  | "none"
+  | "derived"
+  | "source-literal"
+  | "structured-source";
+
+export interface GovernanceTelemetryField {
+  path: string;
+  type: string;
+  purpose: string;
+  carriage: GovernanceTelemetryCarriage;
+  topLevelField: GovernanceTelemetryTopLevelField;
+}
+
+export const GOVERNANCE_TELEMETRY_TOP_LEVEL_FIELDS = [
+  "contractHash",
+  "schemaVersion",
+  "generatedAt",
+  "root",
+  "hook",
+  "git",
+  "summary",
+  "groups",
+  "suppressions",
+  "bypassEvents",
+  "hookEvents",
+  "packageVocabularies",
+  "adoption",
+  "health",
+  "topology",
+  "source",
+  "gateRung",
+  "diffOnly",
+  "failOnWarnings",
+] as const;
+
+export type GovernanceTelemetryTopLevelField =
+  (typeof GOVERNANCE_TELEMETRY_TOP_LEVEL_FIELDS)[number];
+
+export const GOVERNANCE_TELEMETRY_FIELDS = [
+  {
+    path: "schemaVersion",
+    type: '"fragments-governance-report:v1"',
+    purpose: "Pins the accepted wire shape and compatibility policy.",
+    carriage: "none",
+    topLevelField: "schemaVersion",
+  },
+  {
+    path: "generatedAt",
+    type: "ISO-8601 string",
+    purpose: "Records when the CLI produced the report.",
+    carriage: "none",
+    topLevelField: "generatedAt",
+  },
+  {
+    path: "root.{workspaceRoot,packageRoot,packageName}",
+    type: "string fields",
+    purpose: "Identifies the scanned workspace and package roots.",
+    carriage: "none",
+    topLevelField: "root",
+  },
+  {
+    path: "hook.{installedAt,mode,agents[]}",
+    type: "installation metadata",
+    purpose: "Describes the local hook installation that produced evidence.",
+    carriage: "none",
+    topLevelField: "hook",
+  },
+  {
+    path: "git.{baseRef,headSha,branch,repoFullName,pullRequestNumber}",
+    type: "Git and provider identifiers",
+    purpose: "Attaches results to the correct repository, commit and pull request.",
+    carriage: "none",
+    topLevelField: "git",
+  },
+  {
+    path: "summary.{filesScanned,rulesActive,presetsLoaded[],groupCount,occurrenceCount,ignoredCount,classnamesScanned,classnamesDynamic,classnamesResolved,totalFindings,errorCount,warnCount,infoCount,passed}",
+    type: "counts, verdict and active preset names",
+    purpose: "Reports scan volume and result totals without finding rows.",
+    carriage: "derived",
+    topLevelField: "summary",
+  },
+  {
+    path: "summary.ignoredByReason.{reason}",
+    type: "configured reason name → count",
+    purpose: "Counts ignored findings by the reason configured by the repository.",
+    carriage: "derived",
+    topLevelField: "summary",
+  },
+  {
+    path: "summary.countsBySeverity.{error,warn,info}",
+    type: "severity counts",
+    purpose: "Counts findings in each fixed severity bucket.",
+    carriage: "derived",
+    topLevelField: "summary",
+  },
+  {
+    path: "summary.countsByCategory.{category}",
+    type: "configured category name → count",
+    purpose: "Counts findings by the rule categories present in the scan.",
+    carriage: "derived",
+    topLevelField: "summary",
+  },
+  {
+    path: "summary.integrity.{status,declared,fatalForCi,blockingCapable,summary}",
+    type: "governance-integrity verdict",
+    purpose: "Explains whether the resolved policy is capable of enforcement.",
+    carriage: "derived",
+    topLevelField: "summary",
+  },
+  {
+    path: "summary.integrity.families[].{id,armed,reason,remediation}",
+    type: "integrity-family status",
+    purpose: "Explains the enforcement readiness of each governance family.",
+    carriage: "derived",
+    topLevelField: "summary",
+  },
+  {
+    path: "summary.integrity.families[].rules[]",
+    type: "rule identifiers",
+    purpose: "Names the active rules contributing to an integrity family.",
+    carriage: "derived",
+    topLevelField: "summary",
+  },
+  {
+    path: "summary.integrity.armed[]",
+    type: "integrity-family identifiers",
+    purpose: "Names the governance families capable of enforcement.",
+    carriage: "derived",
+    topLevelField: "summary",
+  },
+  {
+    path: "summary.integrity.remediations[]",
+    type: "remediation messages",
+    purpose: "Explains how to make an inert or degraded policy effective.",
+    carriage: "derived",
+    topLevelField: "summary",
+  },
+  {
+    path: "summary.integrity.configDiagnostics[].{code,kind,severity,path,message}",
+    type: "configuration diagnostics",
+    purpose: "Reports inert or conflicting authored governance configuration.",
+    carriage: "structured-source",
+    topLevelField: "summary",
+  },
+  {
+    path: "summary.integrity.roster.{configured,active,inert}",
+    type: "rule roster counts",
+    purpose: "Counts configured, active and inert governance rules.",
+    carriage: "derived",
+    topLevelField: "summary",
+  },
+  {
+    path: "summary.countsByBaselineState.{baselined,new}",
+    type: "baseline-state counts",
+    purpose: "Separates accepted baseline debt from newly introduced findings.",
+    carriage: "derived",
+    topLevelField: "summary",
+  },
+  {
+    path: "groups[].{groupId,ruleId,category,severity,packageRoot,filePath}",
+    type: "finding group metadata",
+    purpose: "Identifies each grouped rule failure and repository-relative path.",
+    carriage: "none",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].message",
+    type: "string",
+    purpose: "Explains the failure and may quote the offending source literal.",
+    carriage: "source-literal",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].normalizedOffense.kind",
+    type: "normalized-offense category",
+    purpose: "Names the kind of source offense represented by the group.",
+    carriage: "derived",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].normalizedOffense.raw",
+    type: "normalized source offense",
+    purpose: "Carries the exact offending source substring.",
+    carriage: "source-literal",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].normalizedOffense.canonical",
+    type: "normalized source offense",
+    purpose: "Carries the derived canonical representation of the offense.",
+    carriage: "derived",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].occurrences[].occurrenceId",
+    type: "stable occurrence identifier",
+    purpose: "Identifies one occurrence within a finding group.",
+    carriage: "derived",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].occurrences[].location.{file,line,column,endLine,endColumn}",
+    type: "repository-relative location",
+    purpose: "Places each occurrence at its exact file/line/column range.",
+    carriage: "none",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].occurrences[].area.{areaId,areaName,criticality,owners[],matchedGlob}",
+    type: "area identifiers, owners and criticality",
+    purpose: "Carries the configured product-area classification for the file.",
+    carriage: "structured-source",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].occurrences[].evidence[].factId",
+    type: "fact identifier",
+    purpose: "Links the occurrence to the extracted fact supporting it.",
+    carriage: "derived",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].occurrences[].evidence[].fact.kind",
+    type: "fact discriminator",
+    purpose: "Names the extracted rule-fact shape.",
+    carriage: "none",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].occurrences[].evidence[].fact.location.{file,line,column,endLine,endColumn}",
+    type: "repository-relative location",
+    purpose: "Locates the source-backed fact used as evidence.",
+    carriage: "none",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].occurrences[].evidence[].fact.{ruleSpecificField}",
+    type: "extensible rule-specific fact fields",
+    purpose:
+      "Carries rule-specific parsed facts; fields may include selectors, properties and source values.",
+    carriage: "structured-source",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].suggestedReplacement.{kind,from,to,certainty,reason}",
+    type: "deterministic replacement",
+    purpose: "Carries the deterministic replacement the CLI can apply.",
+    carriage: "derived",
+    topLevelField: "groups",
+  },
+  {
+    path: "groups[].suggestedReplacement.edit.{file,start,end,replacement}",
+    type: "deterministic edit range",
+    purpose: "Locates and describes the exact edit the CLI can apply.",
+    carriage: "derived",
+    topLevelField: "groups",
+  },
+  {
+    path: "suppressions[].{id,kind,file,line,column,code,expiresOn,attachedLine,attachedTo,directive}",
+    type: "directive identity, location and attachment metadata",
+    purpose: "Reports matched in-source governance directives.",
+    carriage: "none",
+    topLevelField: "suppressions",
+  },
+  {
+    path: "suppressions[].reason",
+    type: "authored directive reason",
+    purpose: "Carries the repository-authored reason for the suppression.",
+    carriage: "source-literal",
+    topLevelField: "suppressions",
+  },
+  {
+    path: "bypassEvents[].{code,file,line}",
+    type: "rule code and source location",
+    purpose: "Records directives that actually bypassed a finding in this run.",
+    carriage: "none",
+    topLevelField: "bypassEvents",
+  },
+  {
+    path: "bypassEvents[].reason",
+    type: "authored directive reason",
+    purpose: "Carries the repository-authored reason for the bypass.",
+    carriage: "source-literal",
+    topLevelField: "bypassEvents",
+  },
+  {
+    path: "bypassEvents[].area.{areaId,areaName,criticality,matchedGlob}",
+    type: "configured product-area metadata",
+    purpose: "Classifies the bypass by its configured product area.",
+    carriage: "structured-source",
+    topLevelField: "bypassEvents",
+  },
+  {
+    path: "hookEvents[].{eventId,kind,ruleId,code,file,mode,agent,timestamp,reasonClass}",
+    type: "bounded hook decision receipts",
+    purpose: "Reports deny, downgrade, suppression and fail-open decisions.",
+    carriage: "none",
+    topLevelField: "hookEvents",
+  },
+  {
+    path: "packageVocabularies[].{source,packageName,status,manifestPath,digest,commit}",
+    type: "compiled canonical-package vocabulary records",
+    purpose: "Publishes package vocabulary proposed by authoritative local discovery.",
+    carriage: "structured-source",
+    topLevelField: "packageVocabularies",
+  },
+  {
+    path: "packageVocabularies[].roots[].{name,members[]}",
+    type: "compiled component roots and members",
+    purpose: "Publishes the canonical component vocabulary discovered from the package.",
+    carriage: "structured-source",
+    topLevelField: "packageVocabularies",
+  },
+  {
+    path: "adoption.{metricVersion,adoptedUsages,ownableUsages}",
+    type: "versioned component-identity usage counts",
+    purpose: "Records the exact numerator and denominator used for adoption history.",
+    carriage: "derived",
+    topLevelField: "adoption",
+  },
+  {
+    path: "adoption.shadows[].{componentKey,displayName,canonicalTarget,usageCount}",
+    type: "bounded component-identity summaries",
+    purpose:
+      "Explains which shadow components are moving the adoption curve without uploading source.",
+    carriage: "derived",
+    topLevelField: "adoption",
+  },
+  {
+    path: "health.{metricVersion,checkedSites,violatingSites}",
+    type: "versioned contract-site counts",
+    purpose:
+      "Records how many sites contract-scope rules inspected and how many distinct sites carried a finding.",
+    carriage: "derived",
+    topLevelField: "health",
+  },
+  {
+    path: "health.populations.{componentUsages,tokenReferences}",
+    type: "per-population site counts",
+    purpose: "Names the measured populations behind the checked-site denominator.",
+    carriage: "derived",
+    topLevelField: "health",
+  },
+  {
+    path: "topology.areaImpact[].{areaId,areaName,beforeOpen,afterOpen,introduced,persistent,resolved}",
+    type: "area identifiers and before/after counts",
+    purpose: "Reports bounded product-area impact totals.",
+    carriage: "derived",
+    topLevelField: "topology",
+  },
+  {
+    path: "contractHash",
+    type: "64-character FCID",
+    purpose: "Pins the exact compiled contract enforced by the run.",
+    carriage: "derived",
+    topLevelField: "contractHash",
+  },
+  {
+    path: "source",
+    type: '"ci"',
+    purpose: "Identifies the report producer.",
+    carriage: "none",
+    topLevelField: "source",
+  },
+  {
+    path: "gateRung",
+    type: '"ci" | "cli"',
+    purpose: "Identifies the enforcement rung that produced the verdict.",
+    carriage: "none",
+    topLevelField: "gateRung",
+  },
+  {
+    path: "diffOnly",
+    type: "boolean",
+    purpose: "States whether the scan was restricted to changed files.",
+    carriage: "none",
+    topLevelField: "diffOnly",
+  },
+  {
+    path: "failOnWarnings",
+    type: "boolean",
+    purpose: "States whether warnings were gating for this run.",
+    carriage: "none",
+    topLevelField: "failOnWarnings",
+  },
+] as const satisfies readonly GovernanceTelemetryField[];
+
+export const GOVERNANCE_TELEMETRY_SOURCE_DISCLOSURE =
+  "The report carries source text in named fields: offending literals, messages that may quote them, structured rule facts, authored suppression and bypass reasons, and compiled package vocabulary. It never uploads whole files, whole source lines or function bodies.";

package/src/index.ts

@@ -7,6 +7,17 @@
 export { BRAND, DEFAULTS } from "./constants.js";
 export type { Brand, Defaults } from "./constants.js";
 
+export {
+  GOVERNANCE_TELEMETRY_FIELDS,
+  GOVERNANCE_TELEMETRY_SOURCE_DISCLOSURE,
+  GOVERNANCE_TELEMETRY_TOP_LEVEL_FIELDS,
+} from "./governance-telemetry.js";
+export type {
+  GovernanceTelemetryCarriage,
+  GovernanceTelemetryField,
+  GovernanceTelemetryTopLevelField,
+} from "./governance-telemetry.js";
+
 // Evidence vocabulary (wire-stable, browser-safe, shared with Inspect).
 export { EVIDENCE_ORDER, canBlock } from "./evidence.js";
 export type { EvidenceGrade, InspectClaim, InspectClaimTier } from "./evidence.js";
@@ -726,6 +737,12 @@ export {
 } from "./rules/index.js";
 export type { RuleTier, PresetRuleState } from "./rules/index.js";
 
+// Contract-site health denominator: how many style-declaration sites the
+// token-vocabulary rule actually judged. Consumed by the CLI's per-scan
+// `contract-site-health:v1` metric next to the identity usage index.
+export { contractTokenReferenceCensus } from "./rules/index.js";
+export type { ContractTokenReferenceCensus } from "./rules/index.js";
+
 // Rule families — the ONE expansion of a broad `govern.rules` id (`tokens/hardcoded-values`)
 // into the concrete rules it stands for. Three copies used to disagree.
 export {

package/src/rules/index.ts

@@ -225,7 +225,11 @@ export { ruleTailwindOffScaleSpacingToken } from "./tailwind-off-scale-spacing-t
 export { ruleTailwindRawColorViaToken } from "./tailwind-raw-color-via-token.js";
 export { ruleTailwindUnknownClass } from "./tailwind-unknown-class.js";
 export { ruleTokensRequireDualFallback } from "./tokens-require-dual-fallback.js";
-export { ruleTokensCssVarsMustBeDefined } from "./tokens-css-vars-must-be-defined.js";
+export {
+  ruleTokensCssVarsMustBeDefined,
+  contractTokenReferenceCensus,
+} from "./tokens-css-vars-must-be-defined.js";
+export type { ContractTokenReferenceCensus } from "./tokens-css-vars-must-be-defined.js";
 export { ruleTokensUpstreamDrift } from "./tokens-upstream-drift.js";
 export { ruleThemeNoThemeCoupledLiteral } from "./theme-no-theme-coupled-literal.js";
 export { ruleA11yRequiredAccessibleName } from "./a11y-required-accessible-name.js";

package/src/rules/tokens-css-vars-must-be-defined.test.ts

@@ -7,7 +7,10 @@ import {
   makeStyleDeclarationFact,
 } from "../index.js";
 import type { Fact } from "../index.js";
-import { ruleTokensCssVarsMustBeDefined } from "./tokens-css-vars-must-be-defined.js";
+import {
+  contractTokenReferenceCensus,
+  ruleTokensCssVarsMustBeDefined,
+} from "./tokens-css-vars-must-be-defined.js";
 
 /**
  * ACCEPTANCE §4 (rule level) + §11 (regression lock).
@@ -242,3 +245,65 @@ describe("ruleTokensCssVarsMustBeDefined", () => {
     expect(reversed).toHaveLength(2);
   });
 });
+
+describe("contractTokenReferenceCensus", () => {
+  function declAt(line: number, value: string): Fact {
+    const file = "src/Card.module.scss";
+    return makeStyleDeclarationFact({
+      file,
+      selector: ".card",
+      declarationPath: `.card:${line}`,
+      property: "color",
+      value,
+      location: { file, line, column: 2 },
+    });
+  }
+
+  it("is unmeasured (undefined) while the rule is inert — no policy fact or no vocabulary", () => {
+    expect(
+      contractTokenReferenceCensus(index([...vocabulary(), declAt(1, "var(--fui-color-accent)")]))
+    ).toBeUndefined();
+    expect(
+      contractTokenReferenceCensus(index([POLICY, declAt(1, "var(--fui-color-accent)")]))
+    ).toBeUndefined();
+  });
+
+  it("counts distinct judged declaration sites — clean and drifting alike, foreign excluded", () => {
+    const census = contractTokenReferenceCensus(
+      index([
+        POLICY,
+        ...vocabulary(),
+        declAt(1, "var(--fui-color-accent)"), // clean, judged
+        declAt(2, "var(--fui-color-brand)"), // drift, judged
+        declAt(3, "var(--swiper-theme-color)"), // foreign, never judged
+        declAt(4, "#39594d"), // no reference at all
+      ])
+    );
+    expect(census).toEqual({ checkedSites: 2 });
+  });
+
+  it("counts a site once regardless of how many judged references it carries", () => {
+    const census = contractTokenReferenceCensus(
+      index([
+        POLICY,
+        ...vocabulary(),
+        declAt(1, "var(--fui-color-accent) var(--fui-space-2) var(--fui-color-brand)"),
+      ])
+    );
+    expect(census).toEqual({ checkedSites: 1 });
+  });
+
+  it("judges only the PRIMARY var() position, exactly like the rule (#17)", () => {
+    // The only primary reference is foreign; the in-contract token sits in
+    // fallback position and must not create a checked site the rule would
+    // never have judged.
+    const census = contractTokenReferenceCensus(
+      index([
+        POLICY,
+        ...vocabulary(),
+        declAt(1, "var(--swiper-theme-color, var(--fui-color-accent))"),
+      ])
+    );
+    expect(census).toEqual({ checkedSites: 0 });
+  });
+});