@usefragments/core 1.7.0 → 1.8.0

package/dist/governance-telemetry.d.ts

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

package/dist/governance-telemetry.js

@@ -0,0 +1,11 @@
+import {
+  GOVERNANCE_TELEMETRY_FIELDS,
+  GOVERNANCE_TELEMETRY_SOURCE_DISCLOSURE,
+  GOVERNANCE_TELEMETRY_TOP_LEVEL_FIELDS
+} from "./chunk-MZ4SW3TP.js";
+export {
+  GOVERNANCE_TELEMETRY_FIELDS,
+  GOVERNANCE_TELEMETRY_SOURCE_DISCLOSURE,
+  GOVERNANCE_TELEMETRY_TOP_LEVEL_FIELDS
+};
+//# sourceMappingURL=governance-telemetry.js.map

package/dist/governance-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}