@usefragments/core 1.5.1 → 1.6.0

package/src/governance-integrity.ts

@@ -18,12 +18,41 @@
  */
 
 import type { CanonicalSource, GovernanceConfig, GovernanceSeverity } from "./governance.js";
+import {
+  normalizePolicyExcludes,
+  policyExcludeMatchesPath,
+  type PolicyExclude,
+} from "./policy-exclude.js";
 import { compileGlobalGovernanceFacts } from "./facts/index.js";
+import type { FactConflict } from "./facts/index.js";
+import { RULE_FAMILY_IDS } from "./rules/families.js";
 import { FRAGMENTS_INTERNAL_RULE_IDS, RULE_TIER } from "./rules/tiers.js";
 import { BLOCKING_RULE_ALLOWLIST } from "./rules/emit-gate.js";
 
 export type GovernanceIntegrityStatus = "healthy" | "degraded" | "inert";
 
+export type InertConfigDiagnosticKind =
+  | "orphan-scale"
+  | "unconsumed-key"
+  | "unmatched-exclude"
+  | "colliding-record"
+  | "overridden-record-severity";
+export type InertConfigDiagnosticCode = "FUI9004" | "FUI9005" | "FUI9006" | "FUI9007" | "FUI9008";
+
+export interface InertConfigDiagnostic {
+  code: InertConfigDiagnosticCode;
+  kind: InertConfigDiagnosticKind;
+  severity: "warn";
+  path: string;
+  message: string;
+}
+
+export interface GovernanceIntegrityRoster {
+  configured: number;
+  active: number;
+  inert: number;
+}
+
 export type GovernanceIntegrityFamilyId =
   | "policy"
   | "components"
@@ -53,6 +82,8 @@ export interface GovernanceIntegrityInput {
   /** Whether `tokens/css-vars-must-be-defined` is activated (caller supplies). */
   cssVarsActive?: boolean;
   mode?: "scan" | "ci" | "hook" | "doctor" | "setup";
+  /** Named, verdict-neutral diagnostics derived from the authored config. */
+  configDiagnostics?: readonly InertConfigDiagnostic[];
 }
 
 export interface GovernanceIntegrityVerdict {
@@ -64,6 +95,8 @@ export interface GovernanceIntegrityVerdict {
   armed: GovernanceIntegrityFamilyId[];
   summary: string;
   remediations: string[];
+  configDiagnostics?: InertConfigDiagnostic[];
+  roster?: GovernanceIntegrityRoster;
 }
 
 interface EffectiveRuleConfig {
@@ -131,6 +164,575 @@ function dedupe(values: string[]): string[] {
   return [...new Set(values)];
 }
 
+const CONSUMED_RULE_IDS = new Set(Object.keys(RULE_TIER));
+const RECOGNIZED_RULE_IDS = new Set([...CONSUMED_RULE_IDS, ...RULE_FAMILY_IDS]);
+// `exclude` is consumed by the scan's finding-override pass (it scopes the rule off
+// the matching paths and reports each drop in the ignored accounting). It was absent
+// from this allow-set, so a working key was diagnosed as inert — the diagnostic was
+// wrong, not the config.
+const RULE_CONFIG_KEYS = new Set(["enabled", "severity", "options", "exclude"]);
+
+const PASSTHROUGH_KEYS = [
+  {
+    path: ["tokens"],
+    keys: [
+      "include",
+      "sources",
+      "packages",
+      "aliases",
+      "upstream",
+      "exclude",
+      "themeSelectors",
+      "enabled",
+      "format",
+      "namespace",
+    ],
+  },
+  {
+    path: ["screenshots"],
+    keys: ["viewport", "threshold", "delay", "outputDir", "themes"],
+  },
+  {
+    path: ["service"],
+    keys: ["poolSize", "idleTimeout"],
+  },
+  {
+    path: ["registry"],
+    keys: ["requireStory", "publicOnly", "categoryDepth", "includeProps", "embedFragments"],
+  },
+  {
+    path: ["govern", "tailwind"],
+    keys: ["palette"],
+  },
+  {
+    path: ["govern", "agent"],
+    keys: ["repairOrder"],
+  },
+  {
+    path: ["govern", "ci"],
+    keys: ["failOnWarnings", "failOnInert"],
+  },
+] as const;
+
+function objectRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+function valueAtPath(value: unknown, path: readonly string[]): unknown {
+  let current = value;
+  for (const segment of path) {
+    const record = objectRecord(current);
+    if (!record) return undefined;
+    current = record[segment];
+  }
+  return current;
+}
+
+function configPath(path: readonly (string | number)[]): string {
+  return path.reduce<string>(
+    (output, segment) =>
+      typeof segment === "number"
+        ? `${output}[${segment}]`
+        : output
+          ? `${output}.${segment}`
+          : segment,
+    ""
+  );
+}
+
+function unconsumedKeyDiagnostic(path: readonly (string | number)[]): InertConfigDiagnostic {
+  const renderedPath = configPath(path);
+  return {
+    code: "FUI9004",
+    kind: "unconsumed-key",
+    severity: "warn",
+    path: renderedPath,
+    message: `${renderedPath} is not consumed by Fragments and has no effect. Remove it or use a supported config key.`,
+  };
+}
+
+/**
+ * Config-record fact kinds: the policy facts that a `govern.*` record compiles into,
+ * paired with the config section that authored them, the authored record that produced
+ * them, and the identity keys their fact id is built from.
+ *
+ * `record` is load-bearing, not decoration. Several kinds in one section key on nothing
+ * (`style.rawColors.forbid`, `style.cssVars.mustBeDefined`, …) or on the same fields
+ * (`jsx.importPath.prefer` and `jsx.component.prefer` both on from/to), so a
+ * section-only diagnostic path makes two DIFFERENT collisions look like one — and the
+ * (code, path) dedupe every consumer runs then discards all but the last, which is the
+ * silence this diagnostic exists to end.
+ *
+ * Deliberately NOT the whole `PolicyFact` union — `token_definition` and
+ * `contract_token` are compiled from token *files*, not authored config records, and
+ * their collisions belong to the token-catalog diagnostics channel. Naming a duplicate
+ * token as a config defect would misattribute it and drown the real signal.
+ */
+const CONFIG_RECORD_FACT_KINDS: Readonly<
+  Record<string, { section: string; record: string; keys: string[] }>
+> = {
+  scale: { section: "govern.scales", record: "scale", keys: ["name"] },
+  scale_value: { section: "govern.scales", record: "scale.values", keys: ["scale", "value"] },
+  style_raw_color_forbidden: {
+    section: "govern.styles",
+    record: "style.rawColors.forbid",
+    keys: [],
+  },
+  style_raw_dimension_forbidden: {
+    section: "govern.styles",
+    record: "style.rawDimensions.forbid",
+    keys: [],
+  },
+  style_property_scale: {
+    section: "govern.styles",
+    record: "style.rawSpacing.mustMatchScale",
+    keys: ["property"],
+  },
+  style_font_size_scale: {
+    section: "govern.styles",
+    record: "style.fontSize.mustMatchScale",
+    keys: [],
+  },
+  style_css_vars_must_be_defined: {
+    section: "govern.styles",
+    record: "style.cssVars.mustBeDefined",
+    keys: [],
+  },
+  jsx_unknown_props_forbidden: {
+    section: "govern.jsx",
+    record: "jsx.unknownProps.forbid",
+    keys: [],
+  },
+  jsx_inline_style_forbidden_raw: {
+    section: "govern.jsx",
+    record: "jsx.inlineStyle.forbidRaw",
+    keys: ["property"],
+  },
+  jsx_import_path_preferred: {
+    section: "govern.jsx",
+    record: "jsx.importPath.prefer",
+    keys: ["from", "to", "imported"],
+  },
+  jsx_component_preferred: {
+    section: "govern.jsx",
+    record: "jsx.component.prefer",
+    keys: ["from", "to"],
+  },
+  prop_value_avoided: {
+    section: "govern.components",
+    record: "prop.value.avoid",
+    keys: ["componentId", "prop", "value"],
+  },
+  prop_value_forbidden: {
+    section: "govern.components",
+    record: "prop.value.forbid",
+    keys: ["componentId", "prop", "value", "pathPattern"],
+  },
+  a11y_name_required: {
+    section: "govern.components",
+    record: "a11y.requireName",
+    keys: ["componentId"],
+  },
+  tailwind_palette_allow: {
+    section: "govern.tailwind",
+    record: "palette.allow",
+    keys: [],
+  },
+  tailwind_palette_deny: { section: "govern.tailwind", record: "palette.deny", keys: [] },
+  tailwind_unknown_class_enabled: {
+    section: "govern.tailwind",
+    record: "unknownClass",
+    keys: [],
+  },
+  governance_rule_config: { section: "govern.rules", record: "rule", keys: ["ruleId"] },
+};
+
+/** The authored settings a reader needs to see to tell two colliding records apart. */
+const COLLISION_DETAIL_KEYS = [
+  "severity",
+  "scale",
+  "prefer",
+  "enabled",
+  "appliesTo",
+  "except",
+  "properties",
+  "because",
+] as const;
+
+function renderFactFields(fact: Record<string, unknown>, keys: readonly string[]): string {
+  return keys
+    .filter((key) => fact[key] !== undefined)
+    .map((key) => `${key}=${Array.isArray(fact[key]) ? JSON.stringify(fact[key]) : fact[key]}`)
+    .join(" ");
+}
+
+/**
+ * Name a config record that the fact index dropped as a first-wins duplicate.
+ *
+ * This is the Layer-6 backstop, not the primary mechanism: merge-time displacement
+ * (`mergeGovernanceConfigs`) already makes the later record win for every shape it can
+ * key. What reaches here is a collision displacement could NOT resolve — two records
+ * that compile to one fact id from different channels (config vs bridge vs Cloud
+ * policy). The invariant it defends: a dropped policy fact is never silent.
+ *
+ * Returns `null` for non-config facts, so usage/token collisions stay on the internal
+ * debug channel.
+ */
+export function collidingRecordDiagnostic(conflict: FactConflict): InertConfigDiagnostic | null {
+  return collidingRecordDiagnostics([conflict])[0] ?? null;
+}
+
+/**
+ * Aggregate every observed collision into one diagnostic per colliding fact id.
+ *
+ * Three same-kind records on one fact id produce TWO conflicts (first-wins keeps the
+ * first and skips both others), and both render the same path. Emitting them separately
+ * meant the `(code, path)` dedupe every consumer runs kept only the last pair, so the
+ * intermediate record was dropped in silence — the same failure the per-kind path fixed
+ * one layer down. Aggregating names the count and lists every dropped setting, and one
+ * user edit still resolves the whole group.
+ */
+export function collidingRecordDiagnostics(
+  conflicts: readonly FactConflict[]
+): InertConfigDiagnostic[] {
+  const groups = new Map<
+    string,
+    { record: string; kept: string; dropped: string[]; keptFallback: string }
+  >();
+
+  for (const conflict of conflicts) {
+    const shape = CONFIG_RECORD_FACT_KINDS[conflict.kept.kind];
+    if (!shape || conflict.kept.kind !== conflict.skipped.kind) continue;
+
+    const keptFact = conflict.kept as unknown as Record<string, unknown>;
+    const skippedFact = conflict.skipped as unknown as Record<string, unknown>;
+    const identity = renderFactFields(keptFact, shape.keys);
+    // The record kind is part of the identity, not just the prose: two singleton-keyed
+    // kinds in one section would otherwise share a path and collapse under the (code,
+    // path) dedupe, dropping one collision silently.
+    const path = `${shape.section}[${identity ? `${shape.record} ${identity}` : shape.record}]`;
+    const group = groups.get(path) ?? {
+      record: shape.record,
+      kept: renderFactFields(keptFact, COLLISION_DETAIL_KEYS),
+      dropped: [],
+      keptFallback: "the first record",
+    };
+    const dropped = renderFactFields(skippedFact, COLLISION_DETAIL_KEYS);
+    group.dropped.push(dropped || `record ${group.dropped.length + 2}`);
+    groups.set(path, group);
+  }
+
+  return [...groups].map(([path, group]) => ({
+    code: "FUI9007" as const,
+    kind: "colliding-record" as const,
+    severity: "warn" as const,
+    path,
+    message:
+      `${path} has ${group.dropped.length + 1} \`${group.record}\` records that compile to the same policy fact — ` +
+      `enforcing ${group.kept || group.keptFallback} and dropping ${group.dropped.join("; ")}. ` +
+      "Author one record for this policy, or scope them apart, so the enforced setting is the one you can read.",
+  }));
+}
+
+/**
+ * The authored config record a policy fact was compiled from, or `null` when the fact
+ * did not come from a `govern.*` record (token facts, usage facts). One table, read by
+ * both the collision diagnostic and the override backstop below.
+ */
+export function configRecordShape(kind: string): { section: string; record: string } | null {
+  const shape = CONFIG_RECORD_FACT_KINDS[kind];
+  return shape ? { section: shape.section, record: shape.record } : null;
+}
+
+/**
+ * Name a `govern.rules` override that outranks the severity a policy record authored.
+ *
+ * The backstop for the path provenance cannot reach. Locally, presets are merged here,
+ * so a preset's broad rule entry is tagged and treated as a default — a user record's
+ * `severity: "error"` wins (report #2 B4). A Cloud-served policy arrives whole: no merge
+ * ran, nothing is tagged, and a broad `tokens/hardcoded-values` entry in it still
+ * displaces the severity a record next to it authored. That cannot be fixed at this
+ * boundary, so it is named instead. Silence is the defect; an unfixable case must at
+ * least speak.
+ */
+export function overriddenRecordSeverityDiagnostic(input: {
+  ruleId: string;
+  /** Config path of the override that won — `govern.rules[...]` or `govern.severity`. */
+  source: string;
+  section: string;
+  record: string;
+  authored: string;
+  enforced: string;
+}): InertConfigDiagnostic {
+  const path = `${input.section}[${input.record}]`;
+  return {
+    code: "FUI9008",
+    kind: "overridden-record-severity",
+    severity: "warn",
+    path,
+    message:
+      `${path} authored severity=${input.authored}, but ${input.source} enforces ` +
+      `severity=${input.enforced} on \`${input.ruleId}\`. The record's severity is not what ` +
+      "gates CI — drop the rule override, or author the record at the severity you want enforced.",
+  };
+}
+
+function collectStrippedKeys(
+  authored: unknown,
+  parsed: unknown,
+  path: readonly (string | number)[],
+  diagnostics: InertConfigDiagnostic[]
+): void {
+  if (Array.isArray(authored)) {
+    if (!Array.isArray(parsed)) return;
+    authored.forEach((item, index) => {
+      collectStrippedKeys(item, parsed[index], [...path, index], diagnostics);
+    });
+    return;
+  }
+
+  const authoredRecord = objectRecord(authored);
+  const parsedRecord = objectRecord(parsed);
+  if (!authoredRecord || !parsedRecord) return;
+
+  for (const key of Object.keys(authoredRecord).sort()) {
+    if (!Object.prototype.hasOwnProperty.call(parsedRecord, key)) {
+      diagnostics.push(unconsumedKeyDiagnostic([...path, key]));
+      continue;
+    }
+    collectStrippedKeys(authoredRecord[key], parsedRecord[key], [...path, key], diagnostics);
+  }
+}
+
+function collectPassthroughKeys(
+  authored: unknown,
+  path: readonly string[],
+  allowed: ReadonlySet<string>,
+  diagnostics: InertConfigDiagnostic[]
+): void {
+  const record = objectRecord(valueAtPath(authored, path));
+  if (!record) return;
+  for (const key of Object.keys(record).sort()) {
+    if (!allowed.has(key)) diagnostics.push(unconsumedKeyDiagnostic([...path, key]));
+  }
+}
+
+function collectRuleConfigKeys(
+  authored: unknown,
+  path: readonly string[],
+  diagnostics: InertConfigDiagnostic[]
+): void {
+  const rules = objectRecord(valueAtPath(authored, path));
+  if (!rules) return;
+  for (const ruleId of Object.keys(rules).sort()) {
+    if (!RECOGNIZED_RULE_IDS.has(ruleId)) {
+      diagnostics.push(unconsumedKeyDiagnostic([...path, ruleId]));
+      continue;
+    }
+    const config = objectRecord(rules[ruleId]);
+    if (!config) continue;
+    for (const key of Object.keys(config).sort()) {
+      if (!RULE_CONFIG_KEYS.has(key)) {
+        diagnostics.push(unconsumedKeyDiagnostic([...path, ruleId, key]));
+      }
+    }
+  }
+}
+
+function collectPassthroughRecordValues(
+  authored: unknown,
+  path: readonly string[],
+  allowed: ReadonlySet<string>,
+  diagnostics: InertConfigDiagnostic[]
+): void {
+  const entries = objectRecord(valueAtPath(authored, path));
+  if (!entries) return;
+  for (const [entryName, value] of Object.entries(entries).sort(([left], [right]) =>
+    left.localeCompare(right)
+  )) {
+    const record = objectRecord(value);
+    if (!record) continue;
+    for (const key of Object.keys(record).sort()) {
+      if (!allowed.has(key)) {
+        diagnostics.push(unconsumedKeyDiagnostic([...path, entryName, key]));
+      }
+    }
+  }
+}
+
+function stableConfigDiagnostics(
+  diagnostics: readonly InertConfigDiagnostic[]
+): InertConfigDiagnostic[] {
+  const unique = new Map<string, InertConfigDiagnostic>();
+  for (const diagnostic of diagnostics) {
+    unique.set(`${diagnostic.code}\0${diagnostic.path}`, diagnostic);
+  }
+  return [...unique.values()].sort(
+    (left, right) =>
+      left.path.localeCompare(right.path) ||
+      left.code.localeCompare(right.code) ||
+      left.message.localeCompare(right.message)
+  );
+}
+
+/**
+ * Diagnose config keys that the permissive validation boundary accepts but the
+ * runtime cannot consume. The parsed config is the source of truth for stripped
+ * keys; explicit allow-sets cover intentional `.passthrough()`/record seams.
+ */
+export function detectUnconsumedConfigKeys(
+  authoredConfig: unknown,
+  parsedConfig: unknown
+): InertConfigDiagnostic[] {
+  const diagnostics: InertConfigDiagnostic[] = [];
+  collectStrippedKeys(authoredConfig, parsedConfig, [], diagnostics);
+
+  for (const boundary of PASSTHROUGH_KEYS) {
+    collectPassthroughKeys(
+      authoredConfig,
+      boundary.path,
+      new Set<string>(boundary.keys),
+      diagnostics
+    );
+  }
+
+  collectRuleConfigKeys(authoredConfig, ["govern", "rules"], diagnostics);
+  collectPassthroughRecordValues(
+    authoredConfig,
+    ["govern", "agents"],
+    new Set(["rules"]),
+    diagnostics
+  );
+  collectPassthroughKeys(authoredConfig, ["govern", "audit"], new Set(), diagnostics);
+  collectPassthroughRecordValues(authoredConfig, ["govern", "runners"], new Set(), diagnostics);
+
+  return stableConfigDiagnostics(diagnostics);
+}
+
+/** Every authored exclude in a policy, paired with the config path that declared it. */
+function authoredPolicyExcludes(
+  policy: GovernanceConfig | undefined
+): Array<{ path: string; scope: string; exclude: PolicyExclude }> {
+  const out: Array<{ path: string; scope: string; exclude: PolicyExclude }> = [];
+  const collect = (path: string, scope: string, raw: unknown) => {
+    for (const exclude of normalizePolicyExcludes(raw) ?? []) {
+      out.push({ path, scope, exclude });
+    }
+  };
+
+  (policy?.styles ?? []).forEach((record, index) => {
+    collect(`govern.styles[${index}].exclude`, record.kind, record.exclude);
+  });
+  (policy?.jsx ?? []).forEach((record, index) => {
+    collect(`govern.jsx[${index}].exclude`, record.kind, record.exclude);
+  });
+  for (const ruleId of Object.keys(policy?.rules ?? {}).sort()) {
+    const record = objectRecord(policy?.rules?.[ruleId]);
+    if (!record) continue;
+    collect(`govern.rules.${ruleId}.exclude`, ruleId, record.exclude);
+  }
+
+  return out;
+}
+
+/**
+ * Diagnose excludes that scope nothing: the key is consumed and the glob is valid, but
+ * it matched no scanned file, so it silently exempts nothing while reading as active
+ * policy. That is the same "declared ≠ armed" failure this module exists to name — a
+ * stale path after a refactor is the common cause.
+ *
+ * `scannedFiles` are repo-relative paths supplied by the caller; core never reads the
+ * filesystem. An empty scan (nothing to compare against) yields no diagnostics rather
+ * than flagging every exclude.
+ */
+export function detectUnmatchedPolicyExcludes(
+  policy: GovernanceConfig | undefined,
+  scannedFiles: readonly string[]
+): InertConfigDiagnostic[] {
+  if (scannedFiles.length === 0) return [];
+  const diagnostics: InertConfigDiagnostic[] = [];
+
+  for (const { path, scope, exclude } of authoredPolicyExcludes(policy)) {
+    if (scannedFiles.some((file) => policyExcludeMatchesPath(exclude, file))) continue;
+    diagnostics.push({
+      code: "FUI9006",
+      kind: "unmatched-exclude",
+      severity: "warn",
+      path,
+      message:
+        `${path} pattern "${exclude.glob}" matched no scanned file, so ${scope} is not ` +
+        "actually scoped by it. Correct the glob to a path this scan covers, or remove it.",
+    });
+  }
+
+  return stableConfigDiagnostics(diagnostics);
+}
+
+interface ScaleBinding {
+  label: string;
+  mechanism: string;
+  scale: string;
+}
+
+function effectiveScaleBindings(policy: GovernanceConfig | undefined): ScaleBinding[] {
+  const bindings: ScaleBinding[] = [];
+  for (const style of policy?.styles ?? []) {
+    if (style.kind === "style.rawSpacing.mustMatchScale") {
+      bindings.push({
+        label: "Spacing properties",
+        mechanism: "style.rawSpacing.mustMatchScale",
+        scale: style.scale,
+      });
+    } else if (style.kind === "style.fontSize.mustMatchScale") {
+      bindings.push({
+        label: "Font-size properties",
+        mechanism: "style.fontSize.mustMatchScale",
+        scale: style.scale,
+      });
+    }
+  }
+  return bindings;
+}
+
+/**
+ * Compare locally declared scales with the effective property-policy graph.
+ * Preset-only scales are not diagnosed because the user did not declare them.
+ */
+export function detectOrphanGovernanceScales(
+  declaredPolicy: GovernanceConfig | undefined,
+  effectivePolicy: GovernanceConfig | undefined
+): InertConfigDiagnostic[] {
+  const bindings = effectiveScaleBindings(effectivePolicy);
+  const referenced = new Set(bindings.map((binding) => binding.scale));
+  const diagnostics: InertConfigDiagnostic[] = [];
+
+  for (const scale of Object.keys(declaredPolicy?.scales ?? {}).sort()) {
+    if (referenced.has(scale)) continue;
+    const path = `govern.scales.${scale}`;
+    const preferred =
+      (scale.toLowerCase().includes("spac")
+        ? bindings.find((binding) => binding.mechanism === "style.rawSpacing.mustMatchScale")
+        : undefined) ??
+      (scale.toLowerCase().includes("font")
+        ? bindings.find((binding) => binding.mechanism === "style.fontSize.mustMatchScale")
+        : undefined) ??
+      bindings[0];
+    const remediation = preferred
+      ? `${preferred.label} are bound to the scale named "${preferred.scale}" — rename the key to "${preferred.scale}" or bind it via ${preferred.mechanism}.`
+      : `Bind it via style.rawSpacing.mustMatchScale or style.fontSize.mustMatchScale, or remove it.`;
+    diagnostics.push({
+      code: "FUI9005",
+      kind: "orphan-scale",
+      severity: "warn",
+      path,
+      message: `${path} is not referenced by any property policy. ${remediation}`,
+    });
+  }
+
+  return stableConfigDiagnostics(diagnostics);
+}
+
 function summarize(
   status: GovernanceIntegrityStatus,
   flags: { componentsArmed: boolean; tokensArmed: boolean; blockingArmed: boolean }
@@ -152,6 +754,7 @@ export function evaluateGovernanceIntegrity(
   input: GovernanceIntegrityInput
 ): GovernanceIntegrityVerdict {
   const configs = effectiveRuleConfigs(input.policy);
+  const configDiagnostics = stableConfigDiagnostics(input.configDiagnostics ?? []);
 
   // --- policy family --------------------------------------------------------
   const policyArmed = input.policy !== undefined && input.policySource !== "none";
@@ -280,6 +883,17 @@ export function evaluateGovernanceIntegrity(
       .filter((remediation): remediation is string => remediation !== undefined)
   );
   const summary = summarize(status, { componentsArmed, tokensArmed, blockingArmed });
+  const configuredRuleCount = [...configs.keys()].filter((ruleId) =>
+    CONSUMED_RULE_IDS.has(ruleId)
+  ).length;
+  const activeRuleCount = [...configs.entries()].filter(
+    ([ruleId, config]) => CONSUMED_RULE_IDS.has(ruleId) && config.enabled
+  ).length;
+  const roster = {
+    configured: configuredRuleCount + configDiagnostics.length,
+    active: activeRuleCount,
+    inert: configDiagnostics.length,
+  };
 
   return {
     status,
@@ -290,5 +904,7 @@ export function evaluateGovernanceIntegrity(
     armed,
     summary,
     remediations,
+    configDiagnostics,
+    roster,
   };
 }

package/src/governance.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it } from "vitest";
-import { compileFragment, defineConfig, defineFragment, g } from "./index.js";
+import {
+  compileFragment,
+  configDeclarationForDiagnostics,
+  defineConfig,
+  defineFragment,
+  g,
+  type FragmentsConfig,
+} from "./index.js";
 
 type ButtonProps = {
   variant?: "primary" | "secondary" | "ghost" | "link";
@@ -12,6 +19,18 @@ function Button(_props: ButtonProps) {
 }
 
 describe("governance DSL", () => {
+  it("preserves the authored declaration for stripped-key diagnostics", () => {
+    const authored = {
+      include: ["src/**/*.fragment.ts"],
+      styles: { spacing: true },
+    };
+    const config = defineConfig(authored as FragmentsConfig);
+
+    expect(config).not.toHaveProperty("styles");
+    expect(configDeclarationForDiagnostics(config)).toBe(authored);
+    expect(Object.keys(config)).toEqual(["include"]);
+  });
+
   it("defineConfig accepts global governance records", () => {
     const config = defineConfig({
       include: ["src/**/*.fragment.ts"],