@ttsc/evidence 0.27.0 → 0.28.0

package/native/graph_nodes.go

@@ -0,0 +1,121 @@
+package evidence
+
+import "github.com/samchon/ttsc/packages/lint/rule"
+
+// GraphNodes publishes the artifacts this project's configured references
+// selected, so a consumer can answer what a citation names rather than only who
+// wrote it.
+//
+// It is a projection of the same corpus Hints projects, and it decides nothing:
+// no coverage, no cardinality, no policy, no diagnostic crosses this boundary.
+// Those are this rule's product and it already delivers them as compile errors;
+// a consumer holding a second copy would hold an unmaintained one.
+//
+// Only selected units are published, which is what makes a document nobody
+// configured a reference for contribute nothing, and what withdraws a unit that
+// named the tag it hid itself behind: selection is where the rule's own answer
+// about its surface already lives, so this asks it rather than repeating it.
+//
+// TypeScript units are not published. The graph already holds every TypeScript
+// declaration as a real node resolved by the checker, and a second node for the
+// same symbol under an evidence address would make one declaration two things.
+func (graphRule) GraphNodes(ctx *rule.GraphContext) []rule.GraphNode {
+  if ctx == nil {
+    return nil
+  }
+  cycle, published := ctx.State.(*graphCycleState)
+  if !published || cycle == nil {
+    return nil
+  }
+  corpus := cycle.Corpus
+  // Addresses of every materialized unit, so a parent can be named by the
+  // address a citation would use rather than by the rule's internal id. A
+  // parent outside the selected set resolves to nothing and the host clears it,
+  // which leaves the child at the top of its chain instead of inventing one.
+  addresses := map[string]string{}
+  for _, inventories := range []map[string]*artifactInventory{
+    corpus.Markdown,
+    corpus.Prisma,
+    corpus.Swagger,
+  } {
+    for _, inventory := range inventories {
+      if inventory == nil {
+        continue
+      }
+      for _, unit := range inventory.Units {
+        if unit != nil {
+          addresses[unit.ID] = unit.Target
+        }
+      }
+    }
+  }
+
+  selected := selectedCompletionUnits(
+    corpus.Config,
+    corpus.Markdown,
+    corpus.Prisma,
+    corpus.Swagger,
+    false,
+  )
+  nodes := make([]rule.GraphNode, 0, len(selected))
+  for _, unit := range selected {
+    // No withdrawal check here on purpose. `selectedCompletionUnits` already
+    // excludes a unit that named the tag it hid itself behind, so a second check
+    // would be a branch nothing can reach — and an unreachable guard reads as a
+    // load-bearing one to the next author, who then trusts it instead of the
+    // selection that actually enforces it.
+    if unit == nil {
+      continue
+    }
+    kind, ok := graphNodeKindOf(unit)
+    if !ok {
+      continue
+    }
+    nodes = append(nodes, rule.GraphNode{
+      Address:  unit.Target,
+      Kind:     kind,
+      Readable: unit.Readable,
+      Parent:   addresses[unit.ParentID],
+      File:     unit.Path,
+      Line:     unit.Line,
+      Aliases:  unit.Aliases,
+    })
+  }
+  return nodes
+}
+
+// graphNodeKindOf maps one materialized unit onto the host's node vocabulary.
+//
+// The symbol is the rule's own selector, so this is a translation rather than a
+// re-derivation: a Prisma relation is its own kind because the parser already
+// separated it from a column, and a Markdown file is its own kind because the
+// heading walk already separated it from a heading.
+//
+// A TypeScript unit reports false. So does an unrecognized symbol: guessing
+// would publish a node under a kind a consumer would then rank and contain as
+// something it is not.
+func graphNodeKindOf(unit *evidenceUnit) (rule.GraphNodeKind, bool) {
+  switch unit.Type {
+  case artifactMarkdown:
+    if unit.Symbol == "file" {
+      return rule.GraphNodeMarkdownDocument, true
+    }
+    return rule.GraphNodeMarkdownSection, true
+  case artifactPrisma:
+    switch unit.Symbol {
+    case "model":
+      return rule.GraphNodePrismaModel, true
+    case "relation":
+      return rule.GraphNodePrismaRelation, true
+    case "column":
+      return rule.GraphNodePrismaColumn, true
+    }
+    return "", false
+  case artifactSwagger:
+    if unit.Symbol == "operation" {
+      return rule.GraphNodeSwaggerOperation, true
+    }
+    return "", false
+  }
+  return "", false
+}

package/native/loader.go

@@ -315,33 +315,50 @@ func (loader *typeScriptLoader) locateInstalledPackage(
   return path.Join("node_modules", name), nil
 }
 
-// resolveLinkedDirectory returns the directory a path ultimately names.
+// resolveLinkedDirectory returns the directory a path ultimately names, and
+// reports whether the chain ended inside the hops this rule follows.
 //
 // `filepath.EvalSymlinks` answers this for a POSIX symlink but not for a
 // Windows junction, which is exactly what pnpm creates for a workspace
 // dependency there: it returns the junction unchanged, so a caller that trusts
 // it walks the link and finds nothing. `os.Readlink` does report a junction's
 // target, and `os.Stat` sees through both, so ask those instead.
-func resolveLinkedDirectory(directory string) string {
+//
+// The second answer is what separates an exhausted chain from a resolved
+// directory, which are one string without it: a caller comparing paths against
+// a link that still names another link cannot tell that it holds one, and that
+// is how the leaf case of #1269 stayed silent until the caller was told.
+//
+// The bound counts links followed, not answers given. A chain that ends exactly
+// on the last hop this rule follows has landed on its directory with no
+// iteration left to look, and it is a chain the filesystem resolves: Linux and
+// Windows follow further, and Darwin stops at this same number, so the boundary
+// sits where the strictest platform's does rather than inside it. So the answer
+// costs one `os.Lstat` in that case and nothing at all in every other, since
+// every earlier ending is a return from inside the loop. Refusing it instead
+// would turn a root that works into an error at the boundary, which is what
+// this rule exists to keep from happening in the other direction.
+func resolveLinkedDirectory(directory string) (string, bool) {
   current := directory
   for range 32 {
     info, err := os.Lstat(current)
     if err != nil || info.IsDir() {
-      return current
+      return current, true
     }
     if target, err := os.Stat(current); err != nil || !target.IsDir() {
-      return current
+      return current, true
     }
     linked, err := os.Readlink(current)
     if err != nil {
-      return current
+      return current, true
     }
     if !filepath.IsAbs(linked) {
       linked = filepath.Join(filepath.Dir(current), linked)
     }
     current = filepath.ToSlash(linked)
   }
-  return current
+  info, err := os.Lstat(current)
+  return current, err == nil && info.IsDir()
 }
 
 // walk lists the project-relative TypeScript files below a directory.
@@ -357,7 +374,13 @@ func (loader *typeScriptLoader) walk(base string) ([]string, string) {
   // nothing, so walking the spelled path finds no files and the reference
   // looks empty rather than unresolvable. Walk what the link points at, and
   // report the files under the spelled path so addresses stay stable.
-  walked := resolveLinkedDirectory(root)
+  // The bound is not refused here. A package whose chain outruns the resolver
+  // walks a link and matches nothing, and the caller already reports that as
+  // an empty population rather than passing over it in silence — so what is
+  // owed there is a better cause, not a diagnostic that does not exist. A
+  // declared base has no such report behind it, which is why
+  // `resolvedBaseDirectory` does refuse.
+  walked, _ := resolveLinkedDirectory(root)
   found := []string{}
   problem := ""
   err := filepath.WalkDir(walked, func(current string, entry fs.DirEntry, err error) error {

package/native/markdown.go

@@ -41,39 +41,64 @@ func loadMarkdownBase(
   inventories map[string]*artifactInventory,
 ) []string {
   problems := []string{}
-  if problem := unreadableBaseProblem(base, artifactMarkdown); problem != "" {
+  if problem := baseDirectoryProblem(base, artifactMarkdown); problem != "" {
     recordPopulationFailure(inventories, artifactMarkdown, base)
     return []string{problem}
   }
-  err := filepath.WalkDir(base.Absolute, func(current string, entry fs.DirEntry, walkErr error) error {
+  from, resolved := resolvedBaseDirectory(base)
+  if !resolved {
+    recordPopulationFailure(inventories, artifactMarkdown, base)
+    return []string{unresolvedBaseProblem(base, artifactMarkdown)}
+  }
+  err := filepath.WalkDir(from, func(current string, entry fs.DirEntry, walkErr error) error {
     if walkErr != nil {
-      relative, ok := relativeProjectPath(base.Absolute, current)
-      relevant := ok &&
-        (matchesConfiguredMarkdownFile(config, base, relative) ||
-          couldContainConfiguredMarkdown(config, base, relative))
-      if !relevant {
-        if entry != nil && entry.IsDir() {
-          return filepath.SkipDir
-        }
-        return nil
+      // The walk root belongs to its population by construction, so a failure
+      // to list it is a failure of the population and is never decided by what
+      // the globs happen to select. The relevance test below answers for an
+      // entry inside the base, and it answers for the base itself only by
+      // accident: its base-relative path is ".", which `couldMatchDescendant`
+      // calls true under a pattern opening with `**` and false under one
+      // opening with a segment. So the one failure that empties the whole
+      // population was reported or discarded by the shape of the globs. The
+      // success branch already exempts the base; this is that exemption on the
+      // error side.
+      //
+      // Returning the error ends the walk and carries the failure to the
+      // handler below, which is where a population-level finding belongs and
+      // where the population is recorded failed rather than healthy and empty.
+      if current == from {
+        return walkErr
       }
-      recordPopulationFailure(inventories, artifactMarkdown, base)
-      problems = append(problems, "Evidence graph could not inspect '"+current+"': "+walkErr.Error()+". Fix filesystem access so configured Markdown sources can be indexed.")
-      if entry != nil && entry.IsDir() {
-        return filepath.SkipDir
+      problem, relevant := unreadableEntryProblem(
+        base,
+        from,
+        "Markdown",
+        current,
+        walkErr,
+        func(relative string) bool {
+          return matchesConfiguredMarkdownFile(config, base, relative) ||
+            couldContainConfiguredMarkdown(config, base, relative)
+        },
+      )
+      if relevant {
+        recordPopulationFailure(inventories, artifactMarkdown, base)
+        problems = append(problems, problem)
       }
-      return nil
+      // `WalkDir` passes a nil entry only for its root, which the guard above
+      // answers, so this error belongs to a directory whose listing failed and
+      // the walk continues with its siblings.
+      return filepath.SkipDir
     }
     if entry.IsDir() {
-      if current != base.Absolute {
-        relative, ok := relativeProjectPath(base.Absolute, current)
+      if current != from {
+        relative, ok := relativeProjectPath(from, current)
         if !ok || !couldContainConfiguredMarkdown(config, base, relative) {
           return filepath.SkipDir
         }
       }
       return nil
     }
-    relative, ok := relativeProjectPath(base.Absolute, current)
+    relative, ok := relativeProjectPath(from, current)
     if !ok {
       return nil
     }
@@ -88,13 +113,13 @@ func loadMarkdownBase(
         Type:       artifactMarkdown,
         LoadFailed: true,
       }
-      problems = append(problems, "Evidence graph could not read Markdown file '"+address.Display+"': "+readErr.Error()+". Fix filesystem access or exclude the file from configured globs.")
+      problems = append(problems, "Evidence graph could not read Markdown file '"+address.Display+"': "+causeText(readErr)+". Fix filesystem access or exclude the file from configured globs.")
       return nil
     }
     inventory, _ := scanMarkdownInventory(address, string(content))
     inventories[address.Key] = inventory
     for _, inventoryProblem := range inventory.Problems {
-      if selectedByMarkdownReference(config, base, relative, inventoryProblem.Symbol) {
+      if selectedByMarkdownPopulation(config, base, relative, inventoryProblem.Symbol) {
         problems = append(problems, inventoryProblem.Message)
       }
     }
@@ -107,7 +132,7 @@ func loadMarkdownBase(
   })
   if err != nil {
     recordPopulationFailure(inventories, artifactMarkdown, base)
-    problems = append(problems, "Evidence graph could not walk Markdown root '"+populationRootLabel(base)+"': "+err.Error()+".")
+    problems = append(problems, unlistableBaseProblem(base, "Markdown", err))
   }
   return problems
 }
@@ -231,14 +256,28 @@ func scanMarkdownInventory(
       }
       // A heading that materializes no unit still opens a region, and that
       // region's content belongs to the nearest heading unit enclosing it. An
-      // H5, and an H2 whose title yields no anchor, are both such headings.
+      // H5 or deeper, and an H2 whose title yields no anchor, are both such
+      // headings.
       // Carrying the previous unit forward instead would attribute the region to
       // whatever unit the walk happened to see last, which is a sibling rather
       // than an ancestor when the skipped heading is shallower: editing text
       // under an anchorless H2 would then expire a review of the H3 above it,
       // which does not contain that text.
       currentDigestHostID = fileUnitID
-      for ancestorLevel := level - 1; ancestorLevel >= 1; ancestorLevel-- {
+      // Start at the deepest level the array holds rather than at this
+      // heading's own. Only H1 through H4 ever write a slot, so a deeper
+      // heading's first candidate ancestor is H4, and reading from its own
+      // level indexed past the end: an H6 walked from 5 into a five-slot array
+      // and took the whole rule down before it materialized anything. An H5
+      // survived that only because it starts at the last valid slot.
+      //
+      // Clamp rather than widen the array. Widening would also seal it, since
+      // `markdownHeading` refuses a level past 6, so this is a choice about
+      // what the type says rather than about safety: the array is indexed by
+      // heading level and sized to hold every materializable one, so its length
+      // is the model. A wider array would carry slots nothing writes and stop
+      // saying so. It is not indexed by ordinal, so slot zero is unused.
+      for ancestorLevel := min(level-1, len(headingUnitIDs)-1); ancestorLevel >= 1; ancestorLevel-- {
         if headingUnitIDs[ancestorLevel] != "" {
           currentDigestHostID = headingUnitIDs[ancestorLevel]
           break
@@ -256,8 +295,12 @@ func scanMarkdownInventory(
             Message: problems[len(problems)-1],
           })
         } else {
+          // Clamped like the digest walk above, though the `level <= 4` around
+          // this block already bounds it. Both walks read the same array, so
+          // both state the same bound rather than one of them depending on a
+          // condition someone could move.
           parentID := fileUnitID
-          for ancestorLevel := level - 1; ancestorLevel >= 1; ancestorLevel-- {
+          for ancestorLevel := min(level-1, len(headingUnitIDs)-1); ancestorLevel >= 1; ancestorLevel-- {
             if headingUnitIDs[ancestorLevel] != "" {
               parentID = headingUnitIDs[ancestorLevel]
               break
@@ -315,7 +358,6 @@ func scanMarkdownInventory(
     }
     for _, review := range parseReviews(comment) {
       inventory.Reviews = append(inventory.Reviews, &evidenceReview{
-        HostID:          hostIDAtLine[line-1],
         SemanticHostIDs: []string{hostIDAtLine[line-1]},
         Reviews:         review.Reviews,
         Type:            artifactMarkdown,
@@ -432,13 +474,34 @@ func couldContainConfiguredMarkdown(
   return false
 }
 
-func selectedByMarkdownReference(
+// selectedByMarkdownPopulation reports whether any configured population reads
+// this file for the symbol a scan problem was filed under.
+//
+// Claims are asked as well as references. A scan problem says the file
+// materialized less than it looks like it should, and that is a hole on either
+// side: a reference loses evidence units, while a claim loses the hosts that owe
+// acknowledgements. The claim side was the silent one. A whitespace-named claim
+// file forms no target, so it contributes no host, drops out of the obligation,
+// and said nothing at all; the same file pointed at by a reference reported the
+// path immediately.
+//
+// The claim is matched on its own symbol set for the reason a reference is: a
+// problem about a kind this population does not read is not its problem. The
+// wildcard symbol still reaches both, which is what carries the unaddressable
+// path, since that one is about the file rather than about any heading kind.
+func selectedByMarkdownPopulation(
   config graphConfig,
   base populationBase,
   path string,
   symbol string,
 ) bool {
   for _, claim := range config.Claims {
+    if claim.Type == artifactMarkdown &&
+      claim.Base.Absolute == base.Absolute &&
+      claim.Files.matches(path) &&
+      (symbol == "*" || claim.Symbols.contains(symbol)) {
+      return true
+    }
     for _, reference := range claim.References {
       if reference.Type == artifactMarkdown &&
         reference.Base.Absolute == base.Absolute &&
@@ -561,7 +624,7 @@ func reportUnreadableMarkdownTags(
   }
   rendered := false
   for index, rawLine := range lines {
-    line := strings.TrimSuffix(rawLine, "
+    line := strings.TrimSuffix(rawLine, "\r")
     if opens, closes := renderedCodeEdges(line); opens || closes {
       rendered = opens
       continue

package/native/model.go

@@ -66,6 +66,11 @@ type claimSpec struct {
   // the resolved Base because the two are produced at different times: the
   // spelling decodes from options alone, while the resolution needs a project
   // identity the decoder never sees.
+  //
+  // `Base.Declared` holds the same spelling once a project identity exists, and
+  // the two are not interchangeable. Read this one before resolution, which is
+  // what `ProjectInputs` does to publish a topology without touching the
+  // filesystem, and read the base's after it, which is what a diagnostic does.
   Root  string
   Base  populationBase
   Files globSet
@@ -112,6 +117,31 @@ type referencePolicy struct {
   // an `@evidenceReview` whose fingerprint matches the cited scope's current
   // content, so a review expires when the thing it reviewed moves.
   RequireReview bool
+  // Checklist moves the obligation from the reference to each selected claim
+  // host: every host answers every unit, rather than the population being
+  // discharged once by whichever host got there first.
+  //
+  // It is not a peer of the cardinality options even though it decodes beside
+  // them. Those tighten a count inside the existing per-reference obligation;
+  // this one gives the obligation a host dimension, which is why the duplicate
+  // and conflict keys below it become per host and why `UniqueEvidence` and
+  // `SingleEvidencePerSymbol` are refused alongside it rather than composed
+  // with it.
+  //
+  // It also takes the subtree away from a positive citation. A citation answers
+  // the item it names and nothing beneath it, and a target naming no item at all
+  // is refused outright as an aggregate.
+  //
+  // Both halves are needed, and only measuring shows why. Refusing the
+  // unselected ancestor alone left the default Markdown selector, where the file
+  // is itself an item, discharging every heading from one `@evidence
+  // docs/rules.md` — the option was a no-op in the first configuration an
+  // adopter writes, silently. Any selector admitting an ancestor beside a
+  // descendant opens the same hole.
+  //
+  // `@evidenceExclude` keeps the cascade, because "none of this applies here" is
+  // one decision however many items it covers.
+  Checklist bool
 }
 
 // evidenceReview is one verification statement bound to its host and target.
@@ -123,15 +153,10 @@ type referencePolicy struct {
 // its review spell one address, and resolving twice would let a review answer a
 // scope its citation does not name.
 type evidenceReview struct {
-  // HostID is the source-position identity, kept only so a carrier with no
-  // semantic identity can still be matched. It must not be the primary key: a
-  // merged identity's halves sit at different positions and therefore carry
-  // different HostIDs, so matching on it alone refuses a review written on
-  // `namespace I` for a citation on `interface I` — placement the graph
-  // elsewhere calls not worth a diagnostic, and which `evidence/review` accepts.
-  HostID string
-  // SemanticHostIDs are the selected graph identities this review is written on,
-  // which is what a citation is matched by.
+  // SemanticHostIDs are the ledger keys this review is written on. They are
+  // normally selected graph identities; an unattached Prisma review uses its
+  // synthetic file identity so the declaration-side position fallback can meet
+  // it. A citation is matched by these keys.
   SemanticHostIDs []string
   // Reviews names which acknowledgement this review answers for. It is part of
   // the match, never inferred: verifying a citation and verifying an exclusion
@@ -275,8 +300,9 @@ type evidenceDeclaration struct {
   ID     string
   HostID string
   // SemanticHostIDs names the selected graph identities that physically host
-  // this declaration. HostID remains the source-position identity used only
-  // for same-block duplicate detection; policy cardinality must not confuse a
+  // this declaration. HostID remains the source-position identity used for
+  // same-block duplicate detection and as the review lookup fallback for a
+  // valid carrier with no semantic host. Policy cardinality must not confuse a
   // declaration position with the public symbol identity it represents.
   SemanticHostIDs []string
   Type            artifactKind
@@ -304,12 +330,19 @@ func (declaration *evidenceDeclaration) valid() bool {
 type artifactInventory struct {
   // Address is the population-relative identity used for units and
   // declarations. It differs from Path when a configured root moves the
-  // address space while diagnostics remain project-relative.
+  // address space while a diagnostic keeps naming the file the way a reader
+  // opens it.
   Address string
-  // Path is the location a diagnostic names: project-relative, ascending with
-  // `..` when the file sits above the project root. It is not the key this
-  // inventory is filed under — that key carries the population base as well,
-  // because one file reached through two roots owns two sets of targets.
+  // Path is the source a diagnostic names. For a file it is spelled the way a
+  // reader opens it: project-relative, ascending with `..` when the file sits
+  // above the project root, and absolute when no relative spelling exists. A
+  // Swagger document is its configured source instead, which may be a URL, and
+  // the diagnostics for that kind print it through `displaySwaggerSource` rather
+  // than from here.
+  //
+  // It is not the key this inventory is filed under — that key carries the
+  // population base as well, because one file reached through two roots owns two
+  // sets of targets.
   Path         string
   Type         artifactKind
   Units        []*evidenceUnit