@ttsc/evidence 0.25.0 → 0.26.1

package/native/graph.go

@@ -70,14 +70,24 @@ func (graphRule) Check(ctx *rule.ProjectContext) {
   )
   problems = append(problems, markdownClaimProblems...)
   problems = append(problems, prismaClaimProblems...)
+  // Governance is judged against the configuration as declared, before
+  // activation drops a claim whose population materialized no unit of its
+  // symbol kind. The question is whether an author put this file in a
+  // population, and a claim that deactivated still declared one: judging after
+  // activation silenced a file whose every declaration the author had
+  // commented out, which is the shape the second repair clause exists for.
+  declared := config
   config = activeGraphConfig(config, markdownClaims, prismaClaims, typescript)
-  extendTypeScriptInventories(root, ctx.Sources, config, typescript)
+  governed := map[string]bool{}
+  extendTypeScriptInventories(root, ctx.Sources, config, typescript, nil)
+  recordGovernedTypeScriptFiles(ctx.Sources, declared, governed)
   markdown, markdownProblems := loadMarkdownInventories(root, config)
   prisma, prismaProblems := loadPrismaInventories(root, config)
   swagger, swaggerProblems := loadSwaggerInventories(root, config)
   problems = append(problems, markdownProblems...)
   problems = append(problems, prismaProblems...)
   problems = append(problems, swaggerProblems...)
+  problems = append(problems, unreadableTypeScriptTags(typescript, governed)...)
   loader := newTypeScriptLoader(root, typescript)
   states, stateProblems := materializeClaimStates(
     config,
@@ -267,6 +277,10 @@ func materializeClaimStates(
         state.Declarations,
         inventories[path].Declarations...,
       )
+      // Reviews travel beside declarations and never among them. They carry no
+      // obligation of their own; they are looked up by host and target when a
+      // reference demands one.
+      state.Reviews = append(state.Reviews, inventories[path].Reviews...)
       if len(claim.ExclusionCarriers.Patterns) != 0 && !carrierPaths[path] {
         for _, declaration := range inventories[path].Declarations {
           state.OutsideCarrier[declaration.ID] = true
@@ -389,13 +403,26 @@ func materializeClaimStates(
         }
       }
       sortUnits(referenceState.Scopes)
+      // The complete materialized population is kept because a review
+      // fingerprint must not depend on this reference's `symbol` selector.
+      // Units and Scopes hold only what this reference selected plus the
+      // ancestors of those, so an unselected descendant appears in neither, and
+      // composing a scope digest from them made the value a function of the
+      // reference rather than of the cited address: a narrowed selector dropped
+      // the subtree from the digest, and two references over one scope demanded
+      // two different values from a tag that carries one token, which no author
+      // could satisfy.
+      for _, unit := range availableUnits {
+        referenceState.Population = append(referenceState.Population, unit)
+      }
+      sortUnits(referenceState.Population)
       if len(referencePaths) != 0 &&
         len(referenceState.Units) == 0 &&
         referenceState.Healthy &&
         !selectedInventoryProblem {
         problems = append(
           problems,
-          claimLabel(claim)+" "+referenceLabel(reference)+" matched "+decimal(len(referencePaths))+" file(s) but materialized no selected evidence units ("+reference.Symbols.names()+"). Select symbol kinds present in those files or correct the reference globs.",
+          claimLabel(claim)+" "+referenceLabel(reference)+" matched "+decimal(len(referencePaths))+" file(s) but found no selected evidence units ("+reference.Symbols.names()+"). Select symbol kinds present in those files or correct the reference globs.",
         )
       }
       state.References = append(state.References, referenceState)
@@ -525,7 +552,7 @@ func evaluateEvidenceGraph(
     if !declaration.valid() {
       problems = append(
         problems,
-        "Malformed @"+string(declaration.Tag)+" declaration at "+declaration.location()+" for "+context+": target and non-empty reason are mandatory. Write '@"+string(declaration.Tag)+" <target> <reason>'.",
+        "Malformed @"+string(declaration.Tag)+" declaration at "+declaration.location()+" for "+context+": target and non-empty reason are mandatory. Write '@"+string(declaration.Tag)+" <target> <reason>'.+untrueTagWarning",
       )
       continue
     }
@@ -591,7 +618,7 @@ func evaluateEvidenceGraph(
       }
       problems = append(
         problems,
-        "Unresolved evidence target '"+declaration.Target+"' at "+declaration.location()+" for "+context+": no configured source materializes that evidence unit. Correct the target, or make one of the named references select the source unit this claim actually uses.",
+        "Unresolved evidence target '"+declaration.Target+"' at "+declaration.location()+" for "+context+": no configured source materializes that evidence unit. Correct the target, make one of the named references select the source unit this claim actually uses, or remove the tag when this host does not answer for that target."+untrueTagWarning,
       )
     case 1:
       for unitID := range candidates {
@@ -628,6 +655,10 @@ func evaluateEvidenceGraph(
         uncertain[declaration.ID] = true
       }
     }
+    // One ledger per claim, because reviews belong to the claim rather than to
+    // any one of its references, and built on first use so a claim with no
+    // reviewing reference pays nothing.
+    var reviewLedgerForClaim *reviewLedger
     for _, reference := range state.References {
       if !reference.Healthy {
         for _, declaration := range state.Declarations {
@@ -668,6 +699,11 @@ func evaluateEvidenceGraph(
       for _, scope := range reference.Scopes {
         scopesByID[scope.ID] = scope
       }
+      // Built on first use and shared by every citation of this reference. The
+      // index spans the whole materialized population, so building it per
+      // citation is quadratic, and nil until a citation actually needs it so a
+      // reference without the policy pays nothing.
+      var reviewScopes *scopeIndex
       for _, declaration := range state.Declarations {
         scopeID := resolved[declaration.ID]
         covered := reference.UnitsByScope[scopeID]
@@ -707,10 +743,34 @@ func evaluateEvidenceGraph(
         if declaration.Tag == tagExclude && reference.Spec.Policy.NoExclude {
           problems = append(
             problems,
-            "Forbidden @evidenceExclude for '"+scopesByID[scopeID].Target+"' at "+declaration.location()+" in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+": noEvidenceExclude requires positive @evidence for this reference. Remove the exclusion and cite the target from a selected "+string(state.Spec.Type)+" host.",
+            "Forbidden @evidenceExclude for '"+scopesByID[scopeID].Target+"' at "+declaration.location()+" in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+": noEvidenceExclude requires positive @evidence for this reference. Remove the exclusion and cite the target from a selected "+string(state.Spec.Type)+" host that answers for it."+untrueTagWarning,
           )
           continue
         }
+        if reference.Spec.Policy.RequireReview {
+          if reviewScopes == nil {
+            // Withdrawn units are absent from Population by construction, and
+            // the scope composite still needs their identities so a member
+            // leaving the public surface moves the fingerprint.
+            reviewScopes = newScopeIndex(
+              append(
+                append([]*evidenceUnit{}, reference.Population...),
+                reference.Hidden...,
+              ),
+            )
+          }
+          if reviewLedgerForClaim == nil {
+            reviewLedgerForClaim = newReviewLedger(state.Reviews)
+          }
+          problems = append(problems, reviewProblems(
+            declaration,
+            scopesByID[scopeID],
+            reference,
+            state,
+            reviewScopes,
+            reviewLedgerForClaim,
+          )...)
+        }
         if declaration.Tag == tagEvidence && declaration.HostID != "" {
           byScope := evidenceByHostAndScope[declaration.HostID]
           if byScope == nil {
@@ -789,7 +849,7 @@ func evaluateEvidenceGraph(
           }
           problems = append(
             problems,
-            "Conflicting acknowledgements for '"+conflictingUnit.Target+"' in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+": @evidence at "+evidence.location()+" overlaps @evidenceExclude at "+exclusion.location()+".",
+            "Conflicting acknowledgements for '"+conflictingUnit.Target+"' in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+": @evidence at "+evidence.location()+" overlaps @evidenceExclude at "+exclusion.location()+". Delete whichever is untrue of this host."+untrueTagWarning,
           )
         }
         if duplicateExclusionUnit != nil {
@@ -810,15 +870,18 @@ func evaluateEvidenceGraph(
           }
           problems = append(
             problems,
-            "Evidence host "+host.Readable+" at "+host.location()+" in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+" cites "+decimal(count)+" distinct selected evidence unit(s); singleEvidencePerSymbol requires exactly 1. Keep positive @evidence citations on this semantic host to exactly one distinct unit.",
+            "Evidence host "+host.Readable+" at "+host.location()+" in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+" cites "+decimal(count)+" distinct selected evidence unit(s); singleEvidencePerSymbol requires exactly 1. Split this host so each unit has one that owns it, or keep positive @evidence citations on this semantic host to exactly one distinct unit.",
           )
         }
       }
       for _, unit := range reference.Units {
         if !acknowledged[unit.ID] {
-          repair := "Use @evidence on a selected " + string(state.Spec.Type) + " host or @evidenceExclude on an eligible carrier."
+          // Building the host is named first because the other two hide it. A
+          // repair offering only the two tags frames the whole problem as which
+          // tag to write, and an unbuilt unit then leaves as an exclusion.
+          repair := "Cite the artifact that answers for this unit with @evidence on a selected " + string(state.Spec.Type) + " host, building that artifact first when none does, or write @evidenceExclude on an eligible carrier when nothing here owes it." + untrueTagWarning
           if reference.Spec.Policy.NoExclude {
-            repair = "Use @evidence on a selected " + string(state.Spec.Type) + " host; this reference forbids @evidenceExclude."
+            repair = "Cite the artifact that answers for this unit with @evidence on a selected " + string(state.Spec.Type) + " host, building that artifact first when none does; this reference forbids @evidenceExclude." + untrueTagWarning
           }
           problems = append(
             problems,
@@ -845,7 +908,7 @@ func evaluateEvidenceGraph(
     if obligations := outsideCarrier[id]; len(obligations) != 0 {
       problems = append(
         problems,
-        "Misplaced @evidenceExclude at "+declaration.location()+" for "+strings.Join(obligations, "; ")+", target '"+displayTarget(declaration.Target)+"': evidenceExcludeCarriers confines this claim's exclusions to "+outsideCarrierGlobs[id]+". Move the tag there, or delete it and implement the target this claim owes.",
+        "Misplaced @evidenceExclude at "+declaration.location()+" for "+strings.Join(obligations, "; ")+", target '"+displayTarget(declaration.Target)+"': evidenceExcludeCarriers confines this claim's exclusions to "+outsideCarrierGlobs[id]+". Move the tag there, or delete it and build what the target requires of this claim."+untrueTagWarning,
       )
       continue
     }
@@ -863,7 +926,7 @@ func evaluateEvidenceGraph(
       }
       problems = append(
         problems,
-        "Out-of-scope @"+string(declaration.Tag)+" host at "+declaration.location()+" for "+strings.Join(obligations, "; ")+", target '"+displayTarget(declaration.Target)+"': host kind '"+host+"' is not selected ("+outOfScopeSelections[id].names()+") by any of these claim obligations. Move the declaration to a selected host, or widen only the claim symbol selector that genuinely owns this target.",
+        "Out-of-scope @"+string(declaration.Tag)+" host at "+declaration.location()+" for "+strings.Join(obligations, "; ")+", target '"+displayTarget(declaration.Target)+"': host kind '"+host+"' is not selected ("+outOfScopeSelections[id].names()+") by any of these claim obligations. Move the declaration to a selected host, or widen the claim symbol selector only when it genuinely owns this target."+untrueTagWarning,
       )
       continue
     }
@@ -875,12 +938,181 @@ func evaluateEvidenceGraph(
     }
     problems = append(
       problems,
-      "Non-participating @"+string(declaration.Tag)+" target '"+displayTarget(declaration.Target)+"' at "+declaration.location()+" for "+context+": the target resolves, but none of this declaration's configured references selects it. Correct the target or reference, or move the tag to an eligible host or exclusion carrier in the claim that owes it; a resolving tag must discharge at least one obligation.",
+      "Non-participating @"+string(declaration.Tag)+" target '"+displayTarget(declaration.Target)+"' at "+declaration.location()+" for "+context+": the target resolves, but none of this declaration's configured references selects it. Correct the target or reference, or move the tag to an eligible host or exclusion carrier in the claim that owes it; a resolving tag must discharge at least one obligation."+untrueTagWarning,
     )
   }
   return problems
 }
 
+// reviewProblems judges one acknowledgement against the review it owes.
+//
+// The review is found by host and target rather than resolved again. A citation
+// and its review spell one address, so resolving the review separately would let
+// it answer a scope its citation does not name, and would report an unresolved
+// target for a tag whose only job is to annotate one that already resolved.
+//
+// Three states are reported and they are mutually exclusive, because each repair
+// subsumes the one after it: without a review there is nothing to carry a
+// fingerprint, and without a fingerprint there is nothing to compare. Every
+// message states the expected value, because completions cannot: the host
+// publishes a rule's corpus only on a cycle where the rule reports nothing, and
+// a stale fingerprint is a report.
+//
+// An empty expected value means this population's loader reported no content
+// for the cited scope. Every bridge digests what it parsed, so that is a loader
+// gap rather than a configuration one, and reporting a mismatch against nothing
+// would name a repair no author can perform. It is silence by design and the
+// only silence here: a bridge that fails reports its own failure, and an
+// unhealthy population is skipped before this runs.
+func reviewProblems(
+  declaration *evidenceDeclaration,
+  scope *evidenceUnit,
+  reference referenceState,
+  state claimState,
+  scopes *scopeIndex,
+  reviews *reviewLedger,
+) []string {
+  if declaration == nil || scope == nil {
+    return nil
+  }
+  // The complete population is what the digest walks, never Units or Scopes.
+  // Both of those are narrowed by this reference's `symbol` selector, so an
+  // unselected descendant is absent from each: a Markdown reference selecting
+  // only `h2` would fingerprint a cited section without the H3 bodies inside it,
+  // and a review of it would never expire however much of that subtree was
+  // rewritten. Worse, two references over one scope under different selectors
+  // would then expect two different digests from a tag that carries exactly one
+  // fingerprint token, and no value an author could write would satisfy both.
+  expected := scopes.fingerprint(scope.ID)
+  if expected == "" {
+    return nil
+  }
+  where := " at " + declaration.location() + " in " +
+    claimLabel(state.Spec) + " " + referenceLabel(reference.Spec)
+  // Every message names the review tag that answers for *this* acknowledgement.
+  // A generic `@evidenceReview` in the repair would send the author of an
+  // exclusion to write the tag that does not answer it, which is the one mistake
+  // the split into two tags exists to prevent.
+  marker := reviewMarkerFor(declaration.Tag)
+  review := reviews.find(declaration)
+  if review == nil {
+    return []string{
+      "Unreviewed @" + string(declaration.Tag) + " for '" + displayTarget(declaration.Target) + "'" + where +
+        ": requireReview asks what was verified, which the reason does not answer. Add '" + marker + " " +
+        displayTarget(declaration.Target) + " #" + expected + " <what you checked>' to the same documentation block, or correct this host when what you checked did not hold. " + reviewExample(declaration.Tag) + untrueReviewWarning,
+    }
+  }
+  if review.Fingerprint == "" {
+    return []string{
+      "Unfingerprinted " + marker + " for '" + displayTarget(declaration.Target) + "'" + where +
+        ": the review states what was checked and does not name the fingerprint of what it checked, so it can never expire. Write '" +
+        marker + " " + displayTarget(declaration.Target) + " #" + expected + " " + firstReviewWords(review.Description) + "'." + untrueReviewWarning,
+    }
+  }
+  if review.Fingerprint != expected {
+    return []string{
+      "Stale " + marker + " for '" + displayTarget(declaration.Target) + "'" + where +
+        ": the review names '#" + review.Fingerprint + "' and that scope now digests to '#" + expected +
+        "'. The cited content changed after this review was written. Read it again and replace the review, including the new fingerprint, or correct this host when the change means it no longer answers for that target." + untrueReviewWarning,
+    }
+  }
+  return nil
+}
+
+// reviewLedger indexes a claim's reviews by the identity they were written on.
+//
+// Two properties are load-bearing and neither is obvious.
+//
+// The key is a *semantic* host identity, never `HostID`. `HostID` is a source
+// position, so the two halves of a merged identity carry different ones: keying on
+// it refused a review written on `namespace I` for a citation on `interface I`,
+// which is placement the graph elsewhere calls not worth a diagnostic and which
+// `evidence/review` accepts. The two rules then disagreed about the same file.
+// `model.go` says as much where it defines the field.
+//
+// It is built once per claim rather than scanned per citation. A linear search
+// over every review, for every declaration, for every reference, is cubic in the
+// three things a large project has most of.
+type reviewLedger struct {
+  byHostAndTarget map[string]*evidenceReview
+}
+
+func newReviewLedger(reviews []*evidenceReview) *reviewLedger {
+  ledger := &reviewLedger{
+    byHostAndTarget: make(map[string]*evidenceReview, len(reviews)),
+  }
+  for _, review := range reviews {
+    if review == nil {
+      continue
+    }
+    for _, hostID := range reviewLedgerHostIDs(review) {
+      key := reviewLedgerKey(hostID, review.Reviews, review.Target)
+      if ledger.byHostAndTarget[key] == nil {
+        ledger.byHostAndTarget[key] = review
+      }
+    }
+  }
+  return ledger
+}
+
+// reviewLedgerHostIDs is every identity a review answers on.
+//
+// The position identity is kept as a fallback for a carrier that has no semantic
+// host at all, such as an unattached Prisma documentation run, whose declarations
+// are keyed the same way.
+func reviewLedgerHostIDs(review *evidenceReview) []string {
+  if len(review.SemanticHostIDs) != 0 {
+    return review.SemanticHostIDs
+  }
+  if review.HostID == "" {
+    return nil
+  }
+  return []string{review.HostID}
+}
+
+// find locates the review bound to one declaration's identity and target.
+func (ledger *reviewLedger) find(
+  declaration *evidenceDeclaration,
+) *evidenceReview {
+  if ledger == nil {
+    return nil
+  }
+  hostIDs := declaration.SemanticHostIDs
+  if len(hostIDs) == 0 && declaration.HostID != "" {
+    hostIDs = []string{declaration.HostID}
+  }
+  for _, hostID := range hostIDs {
+    key := reviewLedgerKey(hostID, declaration.Tag, declaration.Target)
+    if review := ledger.byHostAndTarget[key]; review != nil {
+      return review
+    }
+  }
+  return nil
+}
+
+// reviewLedgerKey composes the one key both sides of the ledger use.
+//
+// Spelled once rather than at each site. The acknowledgement kind is part of it,
+// because verifying a citation and verifying an exclusion are opposite questions
+// and a review of one must never be found for the other; two independent
+// three-part spellings would agree only by inspection, and the day they stop
+// agreeing every review silently stops matching.
+func reviewLedgerKey(hostID string, tag tagKind, target string) string {
+  return hostID + "\x00" + reviewKey(tag, target)
+}
+
+// firstReviewWords echoes enough of a description to show where it goes.
+func firstReviewWords(description string) string {
+  words := strings.Fields(description)
+  if len(words) == 0 {
+    return "<what you checked>"
+  }
+  if len(words) > 6 {
+    words = append(words[:6], "...")
+  }
+  return strings.Join(words, " ")
+}
+
 // declarationEligibleForClaim keeps ownership evidence on the selected host
 // while allowing an intentional exclusion to live on a claim-file carrier.
 func declarationEligibleForClaim(
@@ -904,7 +1136,7 @@ func hiddenTargetProblem(
   hidden *evidenceUnit,
   context string,
 ) string {
-  return "Hidden evidence target '" + displayTarget(declaration.Target) + "' at " + declaration.location() + " for " + context + ": " + hidden.Readable + " at " + hidden.location() + " carries '" + hidden.Hidden + "' in its documentation comment, which withdraws it from the evidence population along with everything nested inside it. Remove the tag if the declaration is public contract, or drop this citation if it is not."
+  return "Hidden evidence target '" + displayTarget(declaration.Target) + "' at " + declaration.location() + " for " + context + ": " + hidden.Readable + " at " + hidden.location() + " carries '" + hidden.Hidden + "' in its documentation comment, which removes it from the evidence population along with everything nested inside it. Remove the tag if the declaration is public contract, or drop this citation if it is not. Do not remove '@hidden' from the target to make this citation legal." + untrueTagWarning
 }
 
 func declarationResolutionUncertain(owners []claimState) bool {
@@ -987,6 +1219,10 @@ func applyTraversedScopes(state *referenceState, reached []*evidenceUnit) {
     }
   }
   sortUnits(state.Scopes)
+  // Every reached declaration, selected or not, so a review fingerprint over a
+  // cited scope walks the structure rather than this reference's selection.
+  state.Population = append(state.Population, reached...)
+  sortUnits(state.Population)
 }
 
 // materializeLocalTypeScriptReference selects modules of the active project
@@ -1037,7 +1273,7 @@ func materializeLocalTypeScriptReference(
   }
   if len(state.Units) == 0 && !selectedInventoryProblem {
     return state, []string{
-      claimLabel(claim) + " " + referenceLabel(reference) + " matched " + decimal(len(paths)) + " file(s) but materialized no selected evidence units (" + reference.Symbols.names() + "). Select symbol kinds present in those files or correct the reference globs.",
+      claimLabel(claim) + " " + referenceLabel(reference) + " matched " + decimal(len(paths)) + " file(s) but found no selected evidence units (" + reference.Symbols.names() + "). Select symbol kinds present in those files or correct the reference globs.",
     }
   }
   return state, nil
@@ -1093,7 +1329,7 @@ func materializePackageGlobReference(
       return state, problems
     }
     return state, []string{
-      claimLabel(claim) + " " + referenceLabel(reference) + " matched no files inside package '" + reference.Package + "' for " + describePatterns(reference.Files) + ". The globs resolve against the package root, not the project root. Check that the installed package actually contains those paths before changing the reference: an empty population demands nothing, so a claim that reaches this state reports full coverage while checking nothing.",
+      claimLabel(claim) + " " + referenceLabel(reference) + " matched no files inside package '" + reference.Package + "' for " + describePatterns(reference.Files) + ". The globs resolve against the package root, not the project root. Check that the installed package actually contains those paths before changing the reference: an empty population contains no units, so this claim reports full coverage without checking anything.",
     }
   }
   // The glob decides membership, the entry decides addresses. A matched module
@@ -1122,7 +1358,7 @@ func materializePackageGlobReference(
   }
   if len(state.Units) == 0 {
     return state, []string{
-      claimLabel(claim) + " " + referenceLabel(reference) + " matched " + decimal(len(state.Paths)) + " file(s) inside package '" + reference.Package + "' but materialized no selected evidence units (" + reference.Symbols.names() + ") reachable from the package entry. Select symbol kinds present in those files, correct the globs, or narrow to modules the entry publishes.",
+      claimLabel(claim) + " " + referenceLabel(reference) + " matched " + decimal(len(state.Paths)) + " file(s) inside package '" + reference.Package + "' but found no selected evidence units (" + reference.Symbols.names() + ") reachable from the package entry. Select symbol kinds present in those files, correct the globs, or narrow to modules the entry publishes.",
     }
   }
   return state, nil