@ttsc/evidence 0.30.4 → 0.31.0

package/native/hints.go

@@ -10,17 +10,21 @@ import (
 // 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.
+// rebuild them from. The graph loads Markdown, Prisma 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.
+// project cycle (`linthost.collectProjectHints` over `runProjectCycle`), so
+// every source the graph reads is read again there. Local Swagger documents are
+// validated by content, and successful HTTP(S) Swagger documents are reused for
+// the process lifetime while failed fetches are retried. A source that fails to
+// load is reported by Check, which fails the rule, which withdraws the corpus.
+// Markdown activation and evaluation share the first observation of each
+// addressed document within that Check. Hints reflects that captured content;
+// an edit after consumption is observed by a later Check, not by projecting
+// this corpus. Reusable downstream delivery still validates consumed proofs.
 type graphCorpus struct {
   Config   graphConfig
   Markdown map[string]*artifactInventory
@@ -70,14 +74,13 @@ func (gate *programDiagnosticGate) first(key string) bool {
 // 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.
+// rather than a choice made here. `linthost.collectProjectHints` skips a rule
+// whose snapshot is not `ProjectRulePassed` or whose state is nil, and
+// `projectReporter.ReportSeverity` marks the rule failed on every finding that
+// is not severity off. 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
@@ -175,7 +178,8 @@ func selectsTypeScriptReference(config graphConfig, exclusion bool) bool {
 // 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.
+// targets follow; Swagger operations come next, being both few and mechanical,
+// and Prisma models and their fields come last.
 //
 // 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

package/native/imports.go

@@ -2,7 +2,6 @@ package evidence
 
 import (
   "encoding/json"
-  "os"
   "path"
   "strings"
 
@@ -109,7 +108,8 @@ func stringLiteralText(node *shimast.Node) string {
   return node.Text()
 }
 
-// typeScriptModuleExtensions are tried in the order TypeScript itself prefers.
+// typeScriptModuleExtensions are the suffixes an extensionless specifier may
+// take, a source file before the declaration file that would describe it.
 var typeScriptModuleExtensions = []string{
   ".ts",
   ".tsx",
@@ -120,8 +120,6 @@ var typeScriptModuleExtensions = []string{
   ".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
@@ -154,6 +152,8 @@ func moduleCandidates(base string) []string {
   return candidates
 }
 
+// splitPackageSpecifier separates a package name from a deep-import subpath,
+// keeping the leading segment of a scoped name attached to its scope.
 func splitPackageSpecifier(specifier string) (string, string) {
   segments := strings.Split(specifier, "/")
   if len(segments) == 0 || segments[0] == "" {
@@ -174,8 +174,9 @@ func splitPackageSpecifier(specifier string) (string, string) {
   return name, subpath
 }
 
-func readPackageManifest(root string, relative string) map[string]json.RawMessage {
-  content, err := os.ReadFile(path.Join(strings.ReplaceAll(root, "\\", "/"), relative))
+func readPackageManifest(root string, relative string, readers ...evidenceInputReader) map[string]json.RawMessage {
+  inputs := inputReader(readers)
+  content, err := inputs.ReadFile(path.Join(strings.ReplaceAll(root, "\\", "/"), relative))
   if err != nil {
     return nil
   }

package/native/input_reader.go

@@ -0,0 +1,83 @@
+package evidence
+
+import (
+  "io/fs"
+  "os"
+  "path/filepath"
+
+  "github.com/samchon/ttsc/packages/lint/rule"
+)
+
+// evidenceInputReader delegates only the operations an inventory or locator
+// actually performs. A nil host reader preserves the original OS operations
+// for manual contexts and native unit callers. It never preloads a population.
+type evidenceInputReader struct{ host rule.ProjectInputReader }
+
+// ReadFile routes actual raw consumption through the generation reader when
+// supplied. Nil manual contexts keep os.ReadFile's bytes and error semantics.
+func (r evidenceInputReader) ReadFile(name string) ([]byte, error) {
+  if r.host != nil {
+    return r.host.ReadFile(name)
+  }
+  return os.ReadFile(name)
+}
+
+// Stat delegates target metadata without changing native link following.
+func (r evidenceInputReader) Stat(name string) (os.FileInfo, error) {
+  if r.host != nil {
+    return r.host.Stat(name)
+  }
+  return os.Stat(name)
+}
+
+// Lstat keeps entry metadata distinct from the followed target; an observing
+// host owns withdrawal when its protocol cannot represent that native entry.
+func (r evidenceInputReader) Lstat(name string) (os.FileInfo, error) {
+  if r.host != nil {
+    return r.host.Lstat(name)
+  }
+  return os.Lstat(name)
+}
+
+// Readlink preserves native target text and errors instead of resolving it.
+func (r evidenceInputReader) Readlink(name string) (string, error) {
+  if r.host != nil {
+    return r.host.Readlink(name)
+  }
+  return os.Readlink(name)
+}
+
+// WalkDir delegates callback ordering and SkipDir/SkipAll behavior. Neither
+// branch preloads unvisited populations or retains a separate walk cache.
+func (r evidenceInputReader) WalkDir(name string, visit fs.WalkDirFunc) error {
+  if r.host != nil {
+    return r.host.WalkDir(name, visit)
+  }
+  return filepath.WalkDir(name, visit)
+}
+
+// Unavailable propagates unsupported external consumption to the observing
+// host; a nil manual context has no reusable input authority to withdraw.
+func (r evidenceInputReader) Unavailable() {
+  if r.host != nil {
+    r.host.Unavailable()
+  }
+}
+
+// inputReader preserves optional variadic-call compatibility: only the first
+// supplied reader belongs to this operation, otherwise native calls remain.
+func inputReader(readers []evidenceInputReader) evidenceInputReader {
+  if len(readers) != 0 {
+    return readers[0]
+  }
+  return evidenceInputReader{}
+}
+
+// EvalSymlinks preserves native resolution and returned spelling; observation
+// coordinates and unresolved-proof refusal belong to the supplied host.
+func (r evidenceInputReader) EvalSymlinks(name string) (string, error) {
+  if r.host != nil {
+    return r.host.EvalSymlinks(name)
+  }
+  return filepath.EvalSymlinks(name)
+}

package/native/inputs.go

@@ -9,12 +9,11 @@ import (
 // ProjectInputs declares the files this rule reads from outside the Program.
 //
 // Markdown, Prisma, and Swagger evidence never enters the TypeScript Program,
-// so until `@ttsc/lint@0.22.0` shipped this contract the host had no way to
-// learn that the graph depended on them. The resulting asymmetry was invisible
-// rather than merely inconvenient: a developer editing code saw fresh
-// diagnostics, because the TypeScript event drove a cycle that reloaded the
-// documents along with it, while a developer editing only a spec section or a
-// schema saw the citation that had just gone stale keep reporting green.
+// so without this declaration the host cannot learn that the graph depends on
+// them. Editing code drives a project cycle that reloads the documents along
+// with it, but editing only a spec section or a schema would raise no event the
+// host associates with this rule, and the citation that had just gone stale
+// would keep reporting green.
 //
 // The host calls this after resolving options and project identity but before
 // loading a Program, so nothing here may read `ctx.Sources`, and nothing here
@@ -84,8 +83,8 @@ func graphProjectInputs(config graphConfig) []rule.ProjectInput {
 //
 // The root is prefixed as the author wrote it rather than resolved here. The
 // host anchors a relative pattern against the same physical project root this
-// rule uses (`linthost/project_inputs.go:151-171`), and it accepts one that
-// ascends or is absolute — so `../../docs/**/*.md` and `C:/shared/docs/**/*.md`
+// rule uses (`normalizeProjectInput` in `linthost/project_inputs.go`), and it
+// accepts one that ascends or is absolute — so `../../docs/**/*.md` and `C:/shared/docs/**/*.md`
 // both arrive at the directory `Check` will read. Resolving it here would
 // duplicate that arithmetic and make this contract depend on a project identity
 // it is supposed to be able to answer without.
@@ -110,14 +109,16 @@ func globInputs(root string, globs globSet) []rule.ProjectInput {
 // localSwaggerInputs publishes a Swagger reference only when it names a file.
 //
 // Withholding the URL form is not a shortcut. The host rejects a remote pattern
-// outright (`linthost/project_inputs.go:159-161`), and one rejected input
-// discards the whole snapshot for every project rule in the run
-// (`linthost/project_inputs.go:113-135`) — so declaring a URL here would take
+// outright (`normalizeProjectInput` in `linthost/project_inputs.go`), and one
+// rejected input discards the whole snapshot for every project rule in the run
+// (`collectProjectInputs` returns the joined error and an empty snapshot) — so declaring a URL here would take
 // this graph's Markdown globs down with it and restore the exact blindness the
 // contract removes.
 //
 // The boundary is also real rather than imposed: a URL has no filesystem event
-// to observe, so its freshness is per-evaluation and belongs to the loader.
+// to observe. The loader reuses a successful fetch until its process ends and
+// retries failed fetches on later evaluations; restarting the session refreshes
+// a remote document that changed while the process remained alive.
 //
 // A local path is published exactly as it normalized, including one that
 // ascends out of the project or names an absolute location. The host resolves

package/native/loader.go

@@ -3,7 +3,6 @@ package evidence
 import (
   "encoding/json"
   "io/fs"
-  "os"
   "path"
   "path/filepath"
   "sort"
@@ -22,6 +21,7 @@ import (
 // that symbol is precisely the one an obligation needs to name — an evidence
 // graph exists to report the operation the frontend never called.
 type typeScriptLoader struct {
+  inputs        evidenceInputReader
   boundary      *populationBase
   root          string
   identityRoot  string
@@ -38,8 +38,10 @@ type typeScriptLoader struct {
 func newTypeScriptLoader(
   root string,
   program map[string]*artifactInventory,
+  readers ...evidenceInputReader,
 ) *typeScriptLoader {
   loader := &typeScriptLoader{
+    inputs:        inputReader(readers),
     root:          strings.ReplaceAll(root, "\\", "/"),
     program:       map[string]*artifactInventory{},
     programIDs:    map[string]*artifactInventory{},
@@ -50,7 +52,7 @@ func newTypeScriptLoader(
     identities:    map[string]typeScriptModuleIdentity{},
     installs:      map[string]installedPackageLocation{},
   }
-  loader.identityRoot, _ = physicalTypeScriptPath(filepath.FromSlash(loader.root))
+  loader.identityRoot, _ = physicalTypeScriptPath(filepath.FromSlash(loader.root), loader.inputs)
   keys := make([]string, 0, len(program))
   for key := range program {
     keys = append(keys, key)
@@ -116,7 +118,7 @@ func (loader *typeScriptLoader) inventory(relative string) (result *artifactInve
 
 func (loader *typeScriptLoader) parse(relative string) *artifactInventory {
   relative = loader.projectPath(relative)
-  content, err := os.ReadFile(resolveProjectPath(loader.root, relative))
+  content, err := loader.inputs.ReadFile(resolveProjectPath(loader.root, relative))
   if err != nil {
     loader.failures[relative] = err.Error()
     return nil
@@ -178,7 +180,7 @@ func (loader *typeScriptLoader) programInventory(module string) *artifactInvento
 // candidate, and a watch cycle resolves every re-export in the population — so
 // callers that can answer from the Program should do that first.
 func (loader *typeScriptLoader) existsOnDisk(relative string) bool {
-  info, err := os.Stat(resolveProjectPath(loader.root, relative))
+  info, err := loader.inputs.Stat(resolveProjectPath(loader.root, relative))
   return err == nil && !info.IsDir()
 }
 
@@ -215,10 +217,10 @@ func (loader *typeScriptLoader) resolveUncached(
       normalized = append(normalized, module)
     }
     // The Program answers first, and not only because it answers without a
-    // syscall. A project that emits beside its sources has both `x.js` and
-    // `x.ts` on disk, and `x.js` is written earlier in the candidate order;
-    // resolving an import to emitted JavaScript would read a module whose
-    // declarations the graph cannot address.
+    // syscall. A module under edit has to be read as the editor has it rather
+    // than as the disk last saw it, which is the rule `inventory` states for a
+    // file already named. The candidates never include emitted JavaScript, so
+    // an emit beside its sources cannot win here.
     for _, candidate := range normalized {
       if loader.programInventory(candidate) != nil {
         if !loader.withinBoundary(candidate) {
@@ -263,7 +265,7 @@ func (loader *typeScriptLoader) moduleIdentity(module string) (string, bool) {
     return cached.Path, cached.Resolved
   }
   absolute := resolveProjectPath(loader.root, module)
-  resolved, ok := physicalTypeScriptPath(absolute)
+  resolved, ok := physicalTypeScriptPath(absolute, loader.inputs)
   // Resolve both sides before taking a relative identity. Canonicalizing only
   // the file makes a project junction or Windows 8.3 root leak the checkout's
   // absolute location into every unit ID and invalidate unchanged reviews.
@@ -272,16 +274,17 @@ func (loader *typeScriptLoader) moduleIdentity(module string) (string, bool) {
   return identity, ok
 }
 
-func physicalTypeScriptPath(absolute string) (string, bool) {
+func physicalTypeScriptPath(absolute string, readers ...evidenceInputReader) (string, bool) {
+  inputs := inputReader(readers)
   current := filepath.Clean(absolute)
   // A directory link can introduce another link in an already-walked parent.
   // Settle the complete path, with the same finite bound as directory chains.
   for range 32 {
-    resolved, ok := resolveLinkedPath(current)
+    resolved, ok := resolveLinkedPath(current, inputs)
     if !ok {
       return resolved, false
     }
-    resolved = expandTypeScriptPath(resolved)
+    resolved = expandTypeScriptPath(resolved, inputs)
     if resolved == current {
       return resolved, true
     }
@@ -293,11 +296,12 @@ func physicalTypeScriptPath(absolute string) (string, bool) {
 // An unsaved or deleted file still has an identity. Expand the deepest existing
 // prefix so Windows short names do not reappear when EvalSymlinks cannot read
 // the complete path, then restore the missing suffix without changing its case.
-func expandTypeScriptPath(absolute string) string {
+func expandTypeScriptPath(absolute string, readers ...evidenceInputReader) string {
+  inputs := inputReader(readers)
   probe := absolute
   suffix := []string{}
   for {
-    if final, err := filepath.EvalSymlinks(probe); err == nil {
+    if final, err := inputs.EvalSymlinks(probe); err == nil {
       if !strings.EqualFold(final, probe) {
         probe = final
       }
@@ -352,7 +356,7 @@ func (loader *typeScriptLoader) projectPath(relative string) string {
 
 // isCleanProjectRelativePath reports whether a path is already the identity
 // `projectPath` would produce: forward slashes, no drive or leading separator,
-// and no `.` or `..` segment to collapse.
+// and no empty, `.`, or `..` segment to collapse.
 func isCleanProjectRelativePath(value string) bool {
   if value == "" || strings.ContainsRune(value, '\\') {
     return false
@@ -447,16 +451,23 @@ type installedPackageLocation struct {
 func (loader *typeScriptLoader) locateInstalledPackage(
   name string,
 ) (string, map[string]json.RawMessage) {
+  current := filepath.Clean(filepath.FromSlash(loader.root))
   prefix := ""
-  for range 32 {
+  for {
     directory := path.Join(prefix, "node_modules", name)
     manifest := readPackageManifest(
       loader.root,
       path.Join(directory, "package.json"),
+      loader.inputs,
     )
     if manifest != nil {
       return directory, manifest
     }
+    parent := filepath.Dir(current)
+    if parent == current {
+      break
+    }
+    current = parent
     prefix = path.Join(prefix, "..")
   }
   return path.Join("node_modules", name), nil
@@ -474,7 +485,7 @@ func (loader *typeScriptLoader) locateInstalledPackage(
 // 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.
+// is how a leaf link stays silent unless the caller is 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
@@ -485,17 +496,18 @@ func (loader *typeScriptLoader) locateInstalledPackage(
 // 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) {
+func resolveLinkedDirectory(directory string, readers ...evidenceInputReader) (string, bool) {
+  inputs := inputReader(readers)
   current := directory
   for range 32 {
-    info, err := os.Lstat(current)
+    info, err := inputs.Lstat(current)
     if err != nil || info.IsDir() {
       return current, true
     }
-    if target, err := os.Stat(current); err != nil || !target.IsDir() {
+    if target, err := inputs.Stat(current); err != nil || !target.IsDir() {
       return current, true
     }
-    linked, err := os.Readlink(current)
+    linked, err := inputs.Readlink(current)
     if err != nil {
       return current, true
     }
@@ -504,7 +516,7 @@ func resolveLinkedDirectory(directory string) (string, bool) {
     }
     current = filepath.ToSlash(linked)
   }
-  info, err := os.Lstat(current)
+  info, err := inputs.Lstat(current)
   return current, err == nil && info.IsDir()
 }
 
@@ -527,10 +539,10 @@ func (loader *typeScriptLoader) walk(base string) ([]string, string) {
   // 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)
+  walked, _ := resolveLinkedDirectory(root, loader.inputs)
   found := []string{}
   problem := ""
-  err := filepath.WalkDir(walked, func(current string, entry fs.DirEntry, err error) error {
+  err := loader.inputs.WalkDir(walked, func(current string, entry fs.DirEntry, err error) error {
     if walked != root {
       if inside, ok := containedProjectPath(walked, filepath.ToSlash(current)); ok {
         current = path.Join(root, inside)