@ttsc/evidence 0.25.0 → 0.26.1

package/lib/typings/TtscEvidenceGraphTypeScriptSymbol.d.ts

@@ -7,30 +7,52 @@
  * and qualified identities keep nested contracts addressable without adding a
  * file path to every target.
  *
- * - `"type"` selects exported interfaces, type aliases, and namespaces. Classes
- *   and enums do not become type units.
+ * - `"type"` selects exported interfaces, type aliases, classes, and namespaces.
+ *   Enums do not become type units.
  * - `"function"` selects exported function declarations, exported `const`
  *   variables initialized with an arrow function or function expression
  *   (including parentheses and type-only expression wrappers), public instance
- *   and static methods of exported classes, function-valued public class fields
- *   (an arrow/function initializer or direct function type), and the same
- *   callable forms exported from namespaces. Constructors and accessors are not
- *   selected.
- * - `"property"` selects property signatures declared directly by exported
- *   interfaces and object-shaped type aliases, plus exported `const`, `let`,
- *   and `var` declarations at module or namespace scope. A `const` initialized
- *   with an arrow or function expression remains a function; every other
- *   variable, including a function-typed declaration or function-valued `let`
- *   or `var`, is a property. Every exported leaf in an object or array binding
- *   pattern is a property. Class fields and methods are not property units.
+ *   and static methods of exported classes, method signatures of exported
+ *   interfaces and object-shaped type aliases, every member of any of those
+ *   three written as a callable (an arrow/function initializer or a function
+ *   type spelled out), and the same callable forms exported from namespaces. An
+ *   overload run is one unit. Constructors and accessors are not selected.
+ * - `"property"` selects every member declared directly by an exported class,
+ *   interface, or object-shaped type alias that is not written as a callable,
+ *   plus exported `const`, `let`, and `var` declarations at module or namespace
+ *   scope. A `const` initialized with an arrow or function expression remains a
+ *   function; every other variable, including a function-typed declaration or
+ *   function-valued `let` or `var`, is a property. A member is the one place
+ *   that rule reads the other way, on all three containers alike: it is a
+ *   property unless it is function-valued **or** annotated with a function type
+ *   written out, either of which makes it a function. The test is syntactic,
+ *   because this rule reads no type checker: `charge: () => void` is a function
+ *   and `charge: Handler` is a property even where `Handler` is an alias of the
+ *   same type, as are a constructor type and a union. Every exported leaf in an
+ *   object or array binding pattern is a property. An accessor, including an
+ *   auto-accessor, is neither, and a `private` or `protected` member is not
+ *   selected whichever syntax declared it. A constructor parameter carrying any
+ *   property modifier declares a field and classifies exactly as the same field
+ *   written in the class body would, whatever the constructor's own visibility
+ *   is, so a `private` or `protected` one materializes nothing, exactly as the
+ *   body form does not. The property modifiers are TypeScript's own five:
+ *   `public`, `protected`, `private`, `readonly`, and `override`. The last is
+ *   the one to know about, because its meaning is about the base class rather
+ *   than about the field, so it does not read as a field declaration. It still
+ *   declares one: on a class extending one that declares `rate`,
+ *   `constructor(override rate: number)` is a public instance field. A
+ *   parameter property's citation belongs on the parameter: a constructor's own
+ *   block hosts nothing, because two parameter properties would leave
+ *   `@evidence` no way to say which field it means.
  *
  * TypeScript units form containment scopes. An interface or object-shaped type
- * alias contains its selected properties. A namespace contains every selected
- * public unit nested below it, including nested namespaces. An `@evidence`
- * target, or an `@evidenceExclude` target allowed by its reference policy,
- * acknowledges its selected node and every selected descendant. A reference
- * selector defines the obligation kinds while their unselected type ancestors
- * remain addressable as aggregate scopes.
+ * alias contains the members it declares, callables included. A class contains
+ * its selected members. A namespace contains every selected public unit nested
+ * below it, including nested namespaces. An `@evidence` target, or an
+ * `@evidenceExclude` target allowed by its reference policy, acknowledges its
+ * selected node and every selected descendant. A reference selector defines the
+ * obligation kinds while their unselected type ancestors remain addressable as
+ * aggregate scopes.
  *
  * Top-level identities use the public export name, and namespace members
  * prepend their namespace, such as `Orders.create`. A namespace itself uses its
@@ -38,16 +60,29 @@
  * exposed as `export { Local as Public }` therefore uses `Public`. A named
  * default declaration keeps its declaration name; anonymous and default-only
  * aliases have no stable target and are not selected. Members of an ambient
- * namespace are public without their own `export` modifier. A type-only
- * namespace alias exposes the namespace, its public type-space descendants, and
- * their type properties without exposing data, functions, or class callables.
- * Type properties use `TypeName.property`. Static class callables use
- * `ClassName.method`; instance callables use `ClassName.prototype.method`.
- * Computed names are not selected, even when their expression is a literal.
- * Literal names must be whitespace-free because a declaration target is one
- * whitespace-delimited token. A dot inside a literal name is rendered
- * unchanged; if that spelling collides with qualification, the target is
- * ambiguous.
+ * namespace are public without their own `export` modifier. A type-only alias
+ * exposes a namespace or a class, its public type-space descendants, and
+ * everything an object-shaped type alias, or an interface no class merges with,
+ * declares, callables included, because every member of those two is
+ * type-space. What it withholds is value-space: namespace data, namespace
+ * functions, and every class member, the last because a member is addressed
+ * through the class value the alias does not expose. An interface merged with a
+ * class is withheld with it, since its members are reached through that same
+ * value. Every type-only export withholds, in every spelling and across every
+ * module boundary: an export list in the declaring file, an inline `export {
+ * type Sale }`, and a re-export in any of `export type { Sale } from`, `export
+ * { type Sale } from`, `export type * from`, and `export type * as api from`. A
+ * member of an object-shaped type alias, or of an interface no class merges
+ * with, uses `TypeName.member`, whether it carries data or is written as a
+ * callable; one declared by an interface merged with a class is an instance
+ * member of that class and uses `ClassName.prototype.member` like the body
+ * form. Static class members use `ClassName.member`; instance members use
+ * `ClassName.prototype.member`, and a constructor parameter property is an
+ * instance member addressed that way. Computed names are not selected, even
+ * when their expression is a literal. Literal names must be whitespace-free
+ * because a declaration target is one whitespace-delimited token. A dot inside
+ * a literal name is rendered unchanged; if that spelling collides with
+ * qualification, the target is ambiguous.
  *
  * These targets deliberately omit file paths. If selected files expose the same
  * qualified target, a declaration using that target is ambiguous; rename or

package/native/comments.go

@@ -0,0 +1,162 @@
+package evidence
+
+// Parser-aware comment enumeration.
+//
+// This is a copy of the enumeration `@ttsc/lint` performs for its own rules,
+// carried here rather than imported from it. `@ttsc/lint` is a peer dependency
+// with a published range, and this package ships Go **source** into a
+// consumer's build against whichever version they installed. A helper this file
+// took from that package would compile here and fail there for every consumer
+// on a release that predates it, which is what a benchmark fixture proved by
+// refusing `undefined: astutil.ForEachComment`. What crosses that boundary is
+// the published rule API and nothing else.
+
+import (
+  "sort"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimscanner "github.com/microsoft/typescript-go/shim/scanner"
+)
+
+type commentToken struct {
+  kind shimast.Kind
+  pos  int
+  end  int
+}
+
+type sourceSpan struct {
+  pos int
+  end int
+}
+
+// forEachCommentToken visits every real comment in `file` in source order.
+//
+// TypeScript's parser, rather than a context-free scanner, owns the lexical
+// goal for regular expressions, templates, and JSX. The parsed AST retains
+// those context-sensitive tokens as exact spans. We treat those spans as
+// opaque and scan only the gaps between them, where slash-shaped bytes are
+// ordinary JavaScript trivia or punctuation. This preserves the scanner's
+// complete comment and line-terminator behavior without guessing whether a
+// slash is division, manually tracking template braces, or special-casing JSX
+// strings. Exact ranges are deduplicated before the callback runs because a
+// recovery AST can expose overlapping token nodes for malformed source.
+func forEachComment(file *shimast.SourceFile, visit func(kind shimast.Kind, pos, end int)) {
+  if file == nil || visit == nil {
+    return
+  }
+  text := file.Text()
+  opaque := parserOpaqueTokenSpans(file)
+  comments := make([]commentToken, 0)
+  seen := make(map[sourceSpan]struct{})
+  gapScanner := shimscanner.NewScanner()
+  collect := func(kind shimast.Kind, pos, end int) {
+    if pos < 0 || end <= pos || end > len(text) {
+      return
+    }
+    span := sourceSpan{pos: pos, end: end}
+    if _, ok := seen[span]; ok {
+      return
+    }
+    seen[span] = struct{}{}
+    comments = append(comments, commentToken{kind: kind, pos: pos, end: end})
+  }
+
+  cursor := 0
+  for _, span := range opaque {
+    if cursor < span.pos {
+      scanCommentGap(gapScanner, text, cursor, span.pos, collect)
+    }
+    if span.end > cursor {
+      cursor = span.end
+    }
+  }
+  if cursor < len(text) {
+    scanCommentGap(gapScanner, text, cursor, len(text), collect)
+  }
+
+  sort.Slice(comments, func(i, j int) bool {
+    if comments[i].pos != comments[j].pos {
+      return comments[i].pos < comments[j].pos
+    }
+    return comments[i].end < comments[j].end
+  })
+  for _, comment := range comments {
+    visit(comment.kind, comment.pos, comment.end)
+  }
+}
+
+// parserOpaqueTokenSpans returns merged source ranges for the parser-owned
+// tokens whose contents a context-free scanner cannot classify: strings,
+// regex literals, template heads/middles/tails, and JSX text. Numeric literals,
+// identifiers, keywords, and punctuation remain in the scanned gaps because
+// they cannot contain comment-shaped source bytes; keeping them there avoids a
+// scanner reset for every ordinary token.
+func parserOpaqueTokenSpans(file *shimast.SourceFile) []sourceSpan {
+  spans := make([]sourceSpan, 0)
+  var walk func(*shimast.Node)
+  walk = func(node *shimast.Node) {
+    if node == nil {
+      return
+    }
+    if parserOpaqueTokenKind(node.Kind) {
+      pos := shimscanner.GetTokenPosOfNode(node, file, false /*includeJSDoc*/)
+      if pos >= 0 && node.End() > pos && node.End() <= len(file.Text()) {
+        spans = append(spans, sourceSpan{pos: pos, end: node.End()})
+      }
+      return
+    }
+    node.ForEachChild(func(child *shimast.Node) bool {
+      walk(child)
+      return false
+    })
+  }
+  walk(file.AsNode())
+  sort.Slice(spans, func(i, j int) bool {
+    if spans[i].pos != spans[j].pos {
+      return spans[i].pos < spans[j].pos
+    }
+    return spans[i].end < spans[j].end
+  })
+  if len(spans) < 2 {
+    return spans
+  }
+  merged := spans[:1]
+  for _, span := range spans[1:] {
+    last := &merged[len(merged)-1]
+    if span.pos <= last.end {
+      if span.end > last.end {
+        last.end = span.end
+      }
+      continue
+    }
+    merged = append(merged, span)
+  }
+  return merged
+}
+
+func parserOpaqueTokenKind(kind shimast.Kind) bool {
+  return kind >= shimast.KindStringLiteral && kind <= shimast.KindLastLiteralToken ||
+    kind >= shimast.KindFirstTemplateToken && kind <= shimast.KindLastTemplateToken
+}
+
+// scanCommentGap scans one parser-classified non-token gap. Context-sensitive
+// token bodies never enter this function, so every comment trivia token it
+// returns is a real source comment. Scanning the isolated gap also preserves
+// CRLF and Unicode line-terminator behavior without range arithmetic in a
+// second comment parser.
+func scanCommentGap(scanner *shimscanner.Scanner, text string, from, to int, visit func(kind shimast.Kind, pos, end int)) {
+  if scanner == nil || from < 0 || to <= from || to > len(text) {
+    return
+  }
+  scanner.SetText(text[from:to])
+  scanner.SetSkipTrivia(false)
+  for {
+    kind := scanner.Scan()
+    switch kind {
+    case shimast.KindEndOfFile:
+      return
+    case shimast.KindSingleLineCommentTrivia, shimast.KindMultiLineCommentTrivia:
+      visit(kind, from+scanner.TokenStart(), from+scanner.TokenEnd())
+    }
+  }
+}

package/native/config.go

@@ -185,6 +185,7 @@ func decodeReference(
       "noEvidenceExclude",
       "uniqueEvidence",
       "singleEvidencePerSymbol",
+      "requireReview",
       "package",
       "root",
       "file",
@@ -306,6 +307,7 @@ func decodeReferencePolicy(
   decodeFlag("noEvidenceExclude", &policy.NoExclude)
   decodeFlag("uniqueEvidence", &policy.UniqueEvidence)
   decodeFlag("singleEvidencePerSymbol", &policy.SingleEvidencePerSymbol)
+  decodeFlag("requireReview", &policy.RequireReview)
   return policy, problems
 }
 

package/native/declaration.go

@@ -102,6 +102,21 @@ func parseCommentDeclarations(
       }
       continue
     }
+    // A review closes the declaration above it in every host, and it does so
+    // regardless of tagBoundaries. That flag answers whether *another tool's*
+    // `@tag` is a boundary, which is a property of the host's comment grammar:
+    // an HTML comment has no field syntax, so `@architecture approved this` is
+    // ordinary prose belonging to the reason above it, and a test pins that.
+    //
+    // A review is not another tool's tag. It belongs to this grammar, so it is
+    // always a boundary. Without this, an `@evidenceReview` written under an
+    // `@evidence` inside one Markdown comment was swallowed into that citation's
+    // reason: the review vanished and the reason grew a sentence its author
+    // addressed to a different question.
+    if _, _, opened := reviewLine(line); opened {
+      flush()
+      continue
+    }
     if jsdoc && strings.HasPrefix(line, "@") {
       flush()
       continue
@@ -220,6 +235,204 @@ func normalizeMarkdownTarget(target string) string {
   return target
 }
 
+// reviewMarkers open a verification statement, one per acknowledgement tag.
+//
+// There are two because the two acknowledgements answer opposite questions and
+// so do their reviews. Verifying an `@evidence` means checking that this
+// declaration does what the cited unit describes. Verifying an
+// `@evidenceExclude` means checking that the unit genuinely does not apply here,
+// which no amount of reading the code can establish and no coverage number can.
+// One tag for both would leave a reader unable to tell which question was
+// answered without finding the sibling tag first, and would let a review of the
+// easier question discharge the harder one.
+//
+// Order is longest marker first, the way `declarationLine` orders its own, so a
+// prefix never shadows a longer tag. The whitespace boundary keeps the four
+// apart on its own — `@evidenceExcludeReview` reaching the `@evidenceExclude`
+// arm is refused exactly as `@evidenceReview` reaching `@evidence` is — but the
+// ordering means that guard is a second line of defense rather than the only one.
+var reviewMarkers = []struct {
+  marker string
+  tag    tagKind
+}{
+  {marker: "@evidenceExcludeReview", tag: tagExclude},
+  {marker: "@evidenceReview", tag: tagEvidence},
+}
+
+// reviewFingerprintLength is how many hex characters a fingerprint presents.
+//
+// Seven is a staleness detector's length, not a security boundary's. A
+// collision costs one review that failed to expire, while the tag stays short
+// enough that an author reads the target beside it instead of scrolling past a
+// full digest.
+const reviewFingerprintLength = 7
+
+// parsedReview is one verification statement read out of a comment.
+//
+// It is deliberately not a `parsedDeclaration`, and the separation is the whole
+// safety property rather than a matter of taste. Every acknowledgement map in
+// `evaluateEvidenceGraph` consumes the declarations of a claim, so a review
+// arriving as a third `tagKind` would discharge coverage, count as a semantic
+// host under `uniqueEvidence`, count as a cited unit under
+// `singleEvidencePerSymbol`, and conflict with an exclusion of the same scope.
+// Each of those is a build turning green because a review was mistaken for
+// evidence. A distinct type cannot reach any of them by construction; a shared
+// type could only be kept out by remembering to, at every one of six sites.
+type parsedReview struct {
+  // Reviews names which acknowledgement this review answers for, so a review of
+  // an exclusion can never discharge a citation's obligation or the reverse.
+  Reviews     tagKind
+  Target      string
+  Fingerprint string
+  Description string
+  LineOffset  int
+}
+
+// marker spells the tag this review was written as, for a diagnostic that has to
+// name the repair rather than describe it.
+func (review parsedReview) marker() string {
+  return reviewMarkerFor(review.Reviews)
+}
+
+// parseReviews reads every verification statement one comment carries.
+//
+// `declarationLine` needs no change to keep these out of the declaration
+// stream, and that is worth stating because it looks like an omission. It
+// matches `@evidence` only when the next character is whitespace, so
+// `@evidenceReview` falls through its loop exactly as `@evidenceExclude`
+// reaching the `@evidence` arm does. The marker namespace was already reserved.
+//
+// The scan is independent for the same reason `todoEntries` is: one tag, one
+// pass, no shared state with the parser whose output must never contain it. Any
+// other `@`-opening line closes the review above it, so a review sharing a
+// block with `@param` or a following `@evidence` swallows neither.
+func parseReviews(comment string) []parsedReview {
+  trimmed := strings.TrimLeftFunc(comment, unicode.IsSpace)
+  leadingLines := strings.Count(comment[:len(comment)-len(trimmed)], "\n")
+  comment = trimmed
+  comment = strings.TrimPrefix(comment, "/**")
+  comment = strings.TrimPrefix(comment, "/*")
+  comment = strings.TrimSuffix(comment, "*/")
+  reviews := []parsedReview{}
+  var pending *parsedReview
+  var body []string
+  flush := func() {
+    if pending == nil {
+      return
+    }
+    target, remainder := splitDeclarationBody(strings.Join(body, "\n"))
+    fingerprint, description := splitReviewFingerprint(remainder)
+    pending.Target = target
+    pending.Fingerprint = fingerprint
+    pending.Description = description
+    reviews = append(reviews, *pending)
+    pending = nil
+    body = nil
+  }
+  for index, rawLine := range strings.Split(comment, "\n") {
+    line := strings.TrimSpace(rawLine)
+    line = strings.TrimSpace(strings.TrimPrefix(line, "*"))
+    line = strings.TrimSpace(strings.TrimPrefix(line, "///"))
+    if reviews, remainder, opened := reviewLine(line); opened {
+      flush()
+      pending = &parsedReview{
+        Reviews:    reviews,
+        LineOffset: leadingLines + index,
+      }
+      body = []string{remainder}
+      continue
+    }
+    if strings.HasPrefix(line, "@") {
+      flush()
+      continue
+    }
+    if pending != nil {
+      body = append(body, line)
+    }
+  }
+  flush()
+  return reviews
+}
+
+// reviewLine reports whether a line opens a review, which acknowledgement it
+// answers for, and with what remainder.
+//
+// The whitespace boundary keeps a longer tag out. `@evidenceReviewed` is some
+// other tool's tag or a typo, and consuming it would attach a review to a
+// citation the author never reviewed. The same boundary is what separates
+// `@evidenceExcludeReview` from `@evidenceExclude` in `declarationLine`, so
+// neither parser can claim the other's tag.
+func reviewLine(line string) (tagKind, string, bool) {
+  for _, candidate := range reviewMarkers {
+    if !strings.HasPrefix(line, candidate.marker) {
+      continue
+    }
+    remainder := line[len(candidate.marker):]
+    if remainder != "" && remainder[0] != ' ' && remainder[0] != '\t' {
+      continue
+    }
+    return candidate.tag, strings.TrimSpace(remainder), true
+  }
+  return "", "", false
+}
+
+// splitReviewFingerprint separates an optional fingerprint from the description.
+//
+// The `#` prefix is required rather than inferred, for the reason
+// `splitInlineLinkBody` records about targets: the token stays
+// self-discriminating through a boundary character instead of a guess. A bare
+// fixed-width hex token would reintroduce that guess, and ordinary prose
+// supplies the counter-examples — `cafe`, `deadbeef`, `beefed`.
+//
+// The exact length is checked as well as the prefix, because `#` alone is not
+// enough. A requirement anchor such as `#req-search-policies` opens a
+// description in exactly that shape, and eating it would strip the author's
+// first words and then report a malformed fingerprint they did not write.
+//
+// No target begins with `#`: a Markdown target carries its anchor after a path,
+// a Prisma target carries its `prisma:` prefix, a Swagger target its method,
+// and a code target its brace. So this only ever reads the position after a
+// target that has already been consumed.
+func splitReviewFingerprint(remainder string) (string, string) {
+  remainder = strings.TrimSpace(remainder)
+  if !strings.HasPrefix(remainder, "#") {
+    return "", remainder
+  }
+  candidate := remainder[1:]
+  description := ""
+  for index, char := range candidate {
+    if unicode.IsSpace(char) {
+      candidate, description = candidate[:index], strings.TrimSpace(candidate[index:])
+      break
+    }
+  }
+  if len(candidate) != reviewFingerprintLength || !isLowerHex(candidate) {
+    // A rejected token stays in the description, because it is usually prose: a
+    // requirement anchor such as `#req-search-policies` opens a sentence in
+    // exactly this shape and the author's words must survive.
+    //
+    // Unless it is the whole body. `#A3F9C1D` alone is a fingerprint whose case
+    // is wrong, not a description, and treating it as prose would let the
+    // shortest wrong path an author can take pass silently: paste the expected
+    // value, get the case wrong, stop, and ship a review that states nothing
+    // while satisfying the non-empty test. Reported as malformed instead.
+    if description == "" {
+      return "", ""
+    }
+    return "", remainder
+  }
+  return candidate, description
+}
+
+func isLowerHex(value string) bool {
+  for _, char := range value {
+    if (char < '0' || char > '9') && (char < 'a' || char > 'f') {
+      return false
+    }
+  }
+  return value != ""
+}
+
 func containsWhitespace(value string) bool {
   for _, char := range value {
     if unicode.IsSpace(char) {

package/native/documented.go

@@ -251,17 +251,17 @@ func documentedHosts(file *shimast.SourceFile) []documentedHost {
 
 // hostNodesOf keeps the declarations that can actually carry a citation.
 //
-// A name can be spelled by a declaration that hosts nothing: a class is not a
-// type unit, so `class C` beside `namespace C` materializes the `C` type from
-// the namespace alone, and the collector registers no host for the class at
-// all. Demanding the block there would send an author's `@evidence` into a
-// position where `evidence/graph` rejects it as an unsupported host — the rule
-// steering citations somewhere a citation cannot live, which is the failure it
-// exists to prevent.
+// A unit's nodes are the positions the identity owns, and owning a position is
+// not the same as being able to hold a tag there. A withdrawn identity records
+// declarations that are deliberately not hosts, and the caller has skipped
+// those before asking, so every position reaching this today is one. That makes
+// the filter remove nothing, which is the point: it states the premise the rule
+// depends on rather than waiting for a form that breaks it.
 //
-// Narrowing to real hosts also keeps this rule's premise exact. The population
-// that must be able to hold a tag is the population a claim can select as a
-// host, and nothing wider.
+// Demanding a block at a position that is not a host would send an author's
+// `@evidence` where `evidence/graph` rejects it as an unsupported host, the
+// rule steering citations somewhere a citation cannot live, which is the
+// failure it exists to prevent.
 func hostNodesOf(
   nodes []*shimast.Node,
   supported map[*shimast.Node]symbolSet,
@@ -280,8 +280,8 @@ func hostNodesOf(
 //
 // The collector records them as it walks, and the merged forms are folded in
 // afterwards, so the slice arrives in neither order. Placement is defined
-// against the declaration that comes first, so that has to be `Node` — and for
-// a variable the enclosing statement wins over its binding, which is where
+// against the declaration that comes first, so that has to be `Node`, and for a
+// variable the enclosing statement wins over its declarator, which is where
 // TypeScript actually attaches the block.
 func orderIdentityDeclarations(hosts []documentedHost) []documentedHost {
   for index := range hosts {