@ttsc/evidence 0.25.0

package/native/health.go

@@ -0,0 +1,45 @@
+package evidence
+
+// recordPopulationFailure preserves a loader failure that belongs to a whole
+// population rather than to one file.
+//
+// A synthetic inventory keeps the existing loader boundary intact: callers
+// still receive the inventories and diagnostics they asked for, while graph
+// materialization can tell "matched nothing" from "could not inspect enough to
+// know what matched". Its NUL-prefixed key cannot be produced by a normalized
+// artifact address and matchingInventoryPaths rejects it through relativeOf.
+func recordPopulationFailure(
+  inventories map[string]*artifactInventory,
+  kind artifactKind,
+  base populationBase,
+) {
+  if inventories == nil || base.Absolute == "" {
+    return
+  }
+  key := "\x00load-failure:" + string(kind) + ":" + base.Absolute
+  inventories[key] = &artifactInventory{
+    Type:        kind,
+    LoadFailed:  true,
+    FailureBase: base.Absolute,
+  }
+}
+
+func populationIsHealthy(
+  inventories map[string]*artifactInventory,
+  base populationBase,
+  paths []string,
+) bool {
+  for _, inventory := range inventories {
+    if inventory != nil &&
+      inventory.LoadFailed &&
+      inventory.FailureBase == base.Absolute {
+      return false
+    }
+  }
+  for _, path := range paths {
+    if inventory := inventories[path]; inventory != nil && inventory.LoadFailed {
+      return false
+    }
+  }
+  return true
+}

package/native/hints.go

@@ -0,0 +1,261 @@
+package evidence
+
+import (
+  "sort"
+  "sync"
+
+  "github.com/samchon/ttsc/packages/lint/rule"
+)
+
+// graphCorpus is what a passing Check publishes for Hints to project.
+//
+// It carries the inventories Check already built rather than the paths to
+// rebuild them from. The graph loads Markdown and Swagger to do its own job, so
+// handing that result forward costs a build nothing; reloading inside Hints
+// would read every source a second time to answer a question the rule had just
+// finished answering.
+//
+// What the editor path does pay is Check itself. A hints request runs a fresh
+// project cycle (`linthost/hints.go:74`), so every source the graph reads is
+// read again there — including an HTTP(S) Swagger reference, which is fetched.
+// That cost is inherent to answering from a current index rather than a stale
+// one, and it is bounded the same way a build is: a source that fails to load
+// is reported by Check, which fails the rule, which withdraws the corpus.
+type graphCorpus struct {
+  Config   graphConfig
+  Markdown map[string]*artifactInventory
+  Prisma   map[string]*artifactInventory
+  Swagger  map[string]*artifactInventory
+}
+
+// graphCycleState is the immutable graph corpus plus the one piece of mutable
+// coordination file rules need during this Program cycle.
+//
+// The host exposes project state, not a lifecycle identifier, to contributor
+// file rules. Keeping the diagnostic gate here gives every parallel file walk
+// one cycle-scoped rendezvous and lets the host discard it on the next watch
+// rebuild. The mutex owns only a set membership check; graph data remains
+// immutable.
+type graphCycleState struct {
+  Corpus      graphCorpus
+  Diagnostics programDiagnosticGate
+}
+
+type programDiagnosticGate struct {
+  mutex    sync.Mutex
+  reported map[string]bool
+}
+
+func (gate *programDiagnosticGate) first(key string) bool {
+  if gate == nil {
+    return true
+  }
+  gate.mutex.Lock()
+  defer gate.mutex.Unlock()
+  if gate.reported == nil {
+    gate.reported = map[string]bool{}
+  }
+  if gate.reported[key] {
+    return false
+  }
+  gate.reported[key] = true
+  return true
+}
+
+// Hints projects the configured evidence population into editor completions.
+//
+// A target has to be reproduced exactly, and the anchor an author cannot recall
+// is the one this offers. The corpus is a value: the host serializes it and the
+// LSP proxy answers from cache long after the lint process exited, so nothing
+// here can be computed per keystroke.
+//
+// The corpus is available only while the graph passes, and that is a host gate
+// rather than a choice made here. `linthost/hints.go:147-149` skips a rule whose
+// snapshot is not `ProjectRulePassed` or whose state is nil, and
+// `projectReporter.Report` sets `failed = true` unconditionally
+// (`linthost/project_engine.go:68-77`). So the cycle that reports an unmet
+// obligation is the cycle that withdraws the completions — which is the cycle an
+// author is most likely to be writing a citation in. Nothing in this package can
+// widen that; it widens upstream, by letting a project rule publish state it
+// reported against.
+func (graphRule) Hints(ctx *rule.HintContext) []rule.Hint {
+  if ctx == nil {
+    return nil
+  }
+  cycle, published := ctx.State.(*graphCycleState)
+  if !published || cycle == nil {
+    return nil
+  }
+  corpus := cycle.Corpus
+  hints := []rule.Hint{}
+  for _, trigger := range evidenceHintTriggers {
+    exclusion := trigger.After == "@evidenceExclude "
+    units := selectedCompletionUnits(
+      corpus.Config,
+      corpus.Markdown,
+      corpus.Prisma,
+      corpus.Swagger,
+      exclusion,
+    )
+    routes := selectsTypeScriptReference(corpus.Config, exclusion)
+    if routes {
+      hints = append(hints, typeScriptRouteHint(trigger))
+    }
+    for _, unit := range units {
+      hints = append(hints, rule.Hint{
+        Insert:  unit.Target,
+        Detail:  unit.Readable,
+        Trigger: trigger,
+      })
+    }
+  }
+  return hints
+}
+
+// evidenceHintTriggers names both tag positions a target can be written in.
+//
+// Each `After` ends where the target begins, which is what makes the text the
+// author has typed so far the editor's filter. The trailing space also keeps
+// the two apart: `"@evidence "` cannot occur inside `"@evidenceExclude "`,
+// because the character following `@evidence` there is `E`.
+var evidenceHintTriggers = []rule.HintTrigger{
+  {Scope: rule.HintScopeJSDoc, After: "@evidence "},
+  {Scope: rule.HintScopeJSDoc, After: "@evidenceExclude "},
+}
+
+// typeScriptRouteHint routes the author into TypeScript's own completion.
+//
+// The host merges a corpus into the upstream response and cannot remove from
+// it, so narrowing TypeScript's symbol list is not available to us. Putting the
+// author inside that list is: once the brace opens, the language service
+// answers every keystroke after it, against the import scope at the cursor —
+// which a corpus built once per Program could never know.
+//
+// The inserted text is deliberately unclosed. `Insert` is verbatim with no
+// snippet expansion, so the cursor lands where the text ends; `{@link }` would
+// park it one character past the only position where completion fires. A
+// missing brace is visible and one keystroke, and the target grammar catches it
+// if forgotten. A cursor in the wrong place is silent.
+func typeScriptRouteHint(trigger rule.HintTrigger) rule.Hint {
+  return rule.Hint{
+    Insert:  "{@link ",
+    Label:   "{@link",
+    Detail:  "TypeScript symbol, resolved through this file's imports",
+    Trigger: trigger,
+  }
+}
+
+// selectsTypeScriptReference reports whether any claim cites TypeScript.
+//
+// The entry is withheld otherwise, because a graph citing only Markdown cannot
+// resolve an inline-link target — offering the grammar there would hand the
+// author an unresolved-target diagnostic for taking a suggestion.
+//
+// The condition is necessarily global. A corpus answers a keystroke with no
+// file context, so it cannot tell which claim owns the file the cursor is in;
+// a repository mixing a TypeScript-citing claim with a Markdown-only one offers
+// the entry in both. Narrowing that needs a per-file corpus, which the contract
+// deliberately does not have.
+func selectsTypeScriptReference(config graphConfig, exclusion bool) bool {
+  for _, claim := range config.Claims {
+    for _, reference := range claim.References {
+      if reference.Type == artifactTypeScript &&
+        (!exclusion || !reference.Policy.NoExclude) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+// selectedCompletionUnits collects the units some configured reference selects,
+// in the order they should be offered.
+//
+// Slice order is the corpus's only ranking channel, so it answers what an
+// author cannot supply from memory. A heading's generated anchor is neither
+// visible in the project tree nor guessable from its text, so selected headings
+// come first; a Markdown file path is typed as easily as it is read, so file
+// targets follow; Swagger operations come last, being both few and mechanical.
+//
+// Order therefore serves the author who is still browsing, and the filter
+// serves the one who is not. No hint sets Label, so the editor lists and
+// filters on the target itself: typing `docs/pricing` narrows to that
+// document's anchors, which is the flow this ranking is for — an author writes
+// a citation because they are implementing a document they have already chosen.
+//
+// Labelling a heading by its text would invert that. `sale` would match and
+// `docs/pricing` would match nothing, two documents sharing a heading would
+// become indistinguishable entries, and the listed text would stop being the
+// inserted text — three costs to serve recall-by-title, which Detail already
+// serves by being visible. Leaving Label empty keeps what is shown and what is
+// written identical by construction.
+//
+// TypeScript units are absent on purpose. TypeScript's own language service
+// completes symbols inside `{@link}` against the scope at the cursor, which a
+// corpus built once per Program cannot know — offering one here would duplicate
+// a correct list with a worse one.
+func selectedCompletionUnits(
+  config graphConfig,
+  markdown map[string]*artifactInventory,
+  prisma map[string]*artifactInventory,
+  swagger map[string]*artifactInventory,
+  exclusion bool,
+) []*evidenceUnit {
+  ranked := map[string][]*evidenceUnit{}
+  seen := map[string]bool{}
+  for _, claim := range config.Claims {
+    for _, reference := range claim.References {
+      if exclusion && reference.Policy.NoExclude {
+        continue
+      }
+      inventories := inventoriesOf(
+        reference.Type,
+        markdown,
+        prisma,
+        swagger,
+        map[string]*artifactInventory{},
+      )
+      for _, path := range matchingReferencePaths(inventories, reference) {
+        inventory := inventories[path]
+        if inventory == nil {
+          continue
+        }
+        for _, unit := range inventory.Units {
+          if unit.Hidden != "" ||
+            !reference.Symbols.contains(unit.Symbol) ||
+            seen[unit.ID] {
+            continue
+          }
+          seen[unit.ID] = true
+          group := completionRank(unit)
+          ranked[group] = append(ranked[group], unit)
+        }
+      }
+    }
+  }
+  units := []*evidenceUnit{}
+  for _, group := range []string{"heading", "file", "operation", "model"} {
+    tier := ranked[group]
+    sort.SliceStable(tier, func(left int, right int) bool {
+      if tier[left].Path != tier[right].Path {
+        return tier[left].Path < tier[right].Path
+      }
+      return tier[left].Line < tier[right].Line
+    })
+    units = append(units, tier...)
+  }
+  return units
+}
+
+func completionRank(unit *evidenceUnit) string {
+  switch {
+  case unit.Type == artifactSwagger:
+    return "operation"
+  case unit.Type == artifactPrisma:
+    return "model"
+  case unit.Symbol == "file":
+    return "file"
+  default:
+    return "heading"
+  }
+}

package/native/imports.go

@@ -0,0 +1,373 @@
+package evidence
+
+import (
+  "encoding/json"
+  "os"
+  "path"
+  "strings"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// importBinding is one name a module brings into scope, and where it came from.
+//
+// Imported is empty for a namespace import, which contributes no segment of its
+// own: `import * as api` makes `api.functional` mean `functional` inside the
+// resolved module, while `import { ISale }` makes `ISale` mean `ISale` there.
+type importBinding struct {
+  Local     string
+  Specifier string
+  Imported  string
+  Namespace bool
+}
+
+// collectImportBindings indexes a file's imports by the local name each binds.
+//
+// Type-only imports are included deliberately. A citation-only import should be
+// `import type`, because it is erased at emit and creates no runtime dependency
+// or cycle — so the form the rule recommends must be the form it can resolve.
+func collectImportBindings(file *shimast.SourceFile) map[string]importBinding {
+  bindings := map[string]importBinding{}
+  if file == nil || file.Statements == nil {
+    return bindings
+  }
+  for _, statement := range file.Statements.Nodes {
+    if statement == nil || statement.Kind != shimast.KindImportDeclaration {
+      continue
+    }
+    declaration := statement.AsImportDeclaration()
+    if declaration == nil || declaration.ImportClause == nil {
+      continue
+    }
+    specifier := stringLiteralText(declaration.ModuleSpecifier)
+    if specifier == "" {
+      continue
+    }
+    clause := declaration.ImportClause.AsImportClause()
+    if clause == nil {
+      continue
+    }
+    if name := declarationName(declaration.ImportClause.Name()); name != "" {
+      bindings[name] = importBinding{
+        Local:     name,
+        Specifier: specifier,
+        Imported:  "default",
+      }
+    }
+    if clause.NamedBindings == nil {
+      continue
+    }
+    switch clause.NamedBindings.Kind {
+    case shimast.KindNamespaceImport:
+      if name := declarationName(clause.NamedBindings.Name()); name != "" {
+        bindings[name] = importBinding{
+          Local:     name,
+          Specifier: specifier,
+          Namespace: true,
+        }
+      }
+    case shimast.KindNamedImports:
+      named := clause.NamedBindings.AsNamedImports()
+      if named == nil || named.Elements == nil {
+        continue
+      }
+      for _, element := range named.Elements.Nodes {
+        if element == nil || element.Kind != shimast.KindImportSpecifier {
+          continue
+        }
+        specifierNode := element.AsImportSpecifier()
+        if specifierNode == nil {
+          continue
+        }
+        local := declarationName(element.Name())
+        imported := local
+        if specifierNode.PropertyName != nil {
+          imported = declarationName(specifierNode.PropertyName)
+        }
+        if local == "" || imported == "" {
+          continue
+        }
+        bindings[local] = importBinding{
+          Local:     local,
+          Specifier: specifier,
+          Imported:  imported,
+        }
+      }
+    }
+  }
+  return bindings
+}
+
+func stringLiteralText(node *shimast.Node) string {
+  if node == nil || node.Kind != shimast.KindStringLiteral {
+    return ""
+  }
+  return node.Text()
+}
+
+// typeScriptModuleExtensions are tried in the order TypeScript itself prefers.
+var typeScriptModuleExtensions = []string{
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".d.ts",
+  ".d.mts",
+  ".d.cts",
+}
+
+// splitPackageSpecifier separates a package name from a deep-import subpath,
+// keeping the leading segment of a scoped name attached to its scope.
+// moduleCandidates lists the files a specifier may denote, most specific first.
+//
+// The `.js` rewrite is not a convenience: under `nodenext` a TypeScript source
+// must spell its sibling as `./x.js`, so refusing to map it back would make the
+// correct import form unresolvable.
+func moduleCandidates(base string) []string {
+  candidates := []string{base}
+  stripped := base
+  for _, emitted := range []string{".js", ".mjs", ".cjs"} {
+    if strings.HasSuffix(base, emitted) {
+      stripped = strings.TrimSuffix(base, emitted)
+      break
+    }
+  }
+  for _, extension := range typeScriptModuleExtensions {
+    candidates = append(candidates, stripped+extension)
+  }
+  for _, extension := range typeScriptModuleExtensions {
+    candidates = append(candidates, path.Join(stripped, "index"+extension))
+  }
+  return candidates
+}
+
+func splitPackageSpecifier(specifier string) (string, string) {
+  segments := strings.Split(specifier, "/")
+  if len(segments) == 0 || segments[0] == "" {
+    return "", ""
+  }
+  count := 1
+  if strings.HasPrefix(segments[0], "@") {
+    if len(segments) < 2 {
+      return "", ""
+    }
+    count = 2
+  }
+  name := strings.Join(segments[:count], "/")
+  subpath := strings.Join(segments[count:], "/")
+  if subpath != "" {
+    subpath = "./" + subpath
+  }
+  return name, subpath
+}
+
+func readPackageManifest(root string, relative string) map[string]json.RawMessage {
+  content, err := os.ReadFile(path.Join(strings.ReplaceAll(root, "\\", "/"), relative))
+  if err != nil {
+    return nil
+  }
+  manifest := map[string]json.RawMessage{}
+  if err := json.Unmarshal(content, &manifest); err != nil {
+    return nil
+  }
+  return manifest
+}
+
+func packageTypeEntry(
+  manifest map[string]json.RawMessage,
+  subpath string,
+) string {
+  if manifest == nil {
+    return ""
+  }
+  key := "."
+  if subpath != "" {
+    key = subpath
+  }
+  if entry := exportsTypeEntry(manifest["exports"], key); entry != "" {
+    return entry
+  }
+  if entry := typesVersionsEntry(manifest["typesVersions"], key); entry != "" {
+    return entry
+  }
+  if subpath == "" {
+    for _, field := range []string{"types", "typings"} {
+      var value string
+      if err := json.Unmarshal(manifest[field], &value); err == nil && value != "" {
+        return value
+      }
+    }
+  }
+  // Every declaration channel above has been asked first, because a package
+  // that names one has said where its declarations are and its runtime entry
+  // is not it. Only when none answers is the runtime entry considered, and
+  // only when it names TypeScript: a source-first workspace package has no
+  // other way to say where its entry is.
+  if entry := exportsRuntimeEntry(manifest["exports"], key); entry != "" {
+    return entry
+  }
+  if subpath != "" {
+    return ""
+  }
+  var main string
+  if err := json.Unmarshal(manifest["main"], &main); err == nil {
+    return typeScriptEntryTarget(main)
+  }
+  return ""
+}
+
+// typeScriptEntryTarget returns target when it names TypeScript itself.
+//
+// A published package points its runtime entry at emitted JavaScript and keeps
+// its declarations behind a `types` condition, so following that entry would
+// address the wrong file. A source-first workspace package has no emit to point
+// at: pnpm links `packages/api` into `node_modules`, and its entry names
+// `./src/index.ts`, which is both what a consumer imports and where the
+// declarations are. Refusing it there leaves a linked package with no
+// resolvable entry, and a reference that cannot find its entry publishes its
+// units under the module that matched instead — which is how
+// `functional.health.get` collapses to `get`.
+func typeScriptEntryTarget(target string) string {
+  for _, extension := range typeScriptModuleExtensions {
+    if strings.HasSuffix(target, extension) {
+      return target
+    }
+  }
+  return ""
+}
+
+// exportsTypeEntry reads the `types` condition of an exports map.
+//
+// The map may be a bare string, a condition object, or a subpath object whose
+// values are either. Only the `types` condition is followed, because a
+// citation addresses declarations rather than the runtime entry `import` and
+// `require` name. [exportsRuntimeEntry] answers for the package that has no
+// declaration channel at all.
+func exportsTypeEntry(raw json.RawMessage, key string) string {
+  if len(raw) == 0 {
+    return ""
+  }
+  // A bare-string exports map names the runtime entry only, and a citation
+  // addresses declarations, so there is nothing here to follow.
+  var direct string
+  if err := json.Unmarshal(raw, &direct); err == nil {
+    return ""
+  }
+  object := map[string]json.RawMessage{}
+  if err := json.Unmarshal(raw, &object); err != nil {
+    return ""
+  }
+  if _, subpaths := object["."]; subpaths || strings.HasPrefix(key, "./") {
+    entry, exists := object[key]
+    if !exists {
+      return ""
+    }
+    return exportsConditionEntry(entry)
+  }
+  if key != "." {
+    return ""
+  }
+  return exportsConditionEntry(raw)
+}
+
+func exportsConditionEntry(raw json.RawMessage) string {
+  if len(raw) == 0 {
+    return ""
+  }
+  var direct string
+  if err := json.Unmarshal(raw, &direct); err == nil {
+    return ""
+  }
+  object := map[string]json.RawMessage{}
+  if err := json.Unmarshal(raw, &object); err != nil {
+    return ""
+  }
+  if types, exists := object["types"]; exists {
+    var value string
+    if err := json.Unmarshal(types, &value); err == nil {
+      return value
+    }
+    return exportsConditionEntry(types)
+  }
+  for _, condition := range []string{"import", "default"} {
+    if nested, exists := object[condition]; exists {
+      if entry := exportsConditionEntry(nested); entry != "" {
+        return entry
+      }
+    }
+  }
+  return ""
+}
+
+// exportsRuntimeEntry reads the runtime entry of an exports map, and returns
+// it only when it names TypeScript.
+//
+// It mirrors [exportsTypeEntry] over the same three shapes, following the
+// target a consumer actually imports rather than the `types` condition. That
+// target is the declarations exactly when it is TypeScript, which is the
+// source-first workspace package [typeScriptEntryTarget] describes.
+func exportsRuntimeEntry(raw json.RawMessage, key string) string {
+  if len(raw) == 0 {
+    return ""
+  }
+  var direct string
+  if err := json.Unmarshal(raw, &direct); err == nil {
+    if key != "." {
+      return ""
+    }
+    return typeScriptEntryTarget(direct)
+  }
+  object := map[string]json.RawMessage{}
+  if err := json.Unmarshal(raw, &object); err != nil {
+    return ""
+  }
+  if _, subpaths := object["."]; subpaths || strings.HasPrefix(key, "./") {
+    entry, exists := object[key]
+    if !exists {
+      return ""
+    }
+    return runtimeConditionEntry(entry)
+  }
+  if key != "." {
+    return ""
+  }
+  return runtimeConditionEntry(raw)
+}
+
+func runtimeConditionEntry(raw json.RawMessage) string {
+  if len(raw) == 0 {
+    return ""
+  }
+  var direct string
+  if err := json.Unmarshal(raw, &direct); err == nil {
+    return typeScriptEntryTarget(direct)
+  }
+  object := map[string]json.RawMessage{}
+  if err := json.Unmarshal(raw, &object); err != nil {
+    return ""
+  }
+  for _, condition := range []string{"import", "default", "require"} {
+    if nested, exists := object[condition]; exists {
+      if entry := runtimeConditionEntry(nested); entry != "" {
+        return entry
+      }
+    }
+  }
+  return ""
+}
+
+func typesVersionsEntry(raw json.RawMessage, key string) string {
+  if len(raw) == 0 || key != "." {
+    return ""
+  }
+  versions := map[string]map[string][]string{}
+  if err := json.Unmarshal(raw, &versions); err != nil {
+    return ""
+  }
+  for _, mapping := range versions {
+    if entries, exists := mapping["*"]; exists && len(entries) != 0 {
+      return entries[0]
+    }
+  }
+  return ""
+}