@ttsc/evidence 0.25.0

package/native/prisma_cache.go

@@ -0,0 +1,213 @@
+package evidence
+
+import (
+  "crypto/sha256"
+  "encoding/hex"
+  "os"
+  "strings"
+  "sync"
+)
+
+// prismaCacheLimit bounds the cache so a resident host cannot grow without end.
+// A project declares one schema set, so several entries only accumulate as its
+// bytes change; the bound is a backstop against a pathological session rather
+// than a tuning knob.
+const prismaCacheLimit = 16
+
+// prismaSchemas remembers parse outcomes by schema content.
+//
+// This is the rule's own state, not the project state the host publishes, for
+// the reason `swaggerDocuments` states at length: the contributor API exposes
+// no disposal hook, both resident hosts are line-protocol loops in one process,
+// and a project rule runs before any file rule so the parallel walk never
+// reaches it.
+var prismaSchemas = newPrismaCache()
+
+// prismaSetOutcome is what one schema set's bytes parsed to.
+//
+// Failure is remembered as deliberately as success. A schema the parser rejects
+// is one the author is midway through fixing, and while they fix it every
+// unrelated TypeScript save would otherwise pay a fresh process start to be
+// told the same thing again. Nothing is cached forever: repairing the schema
+// changes its bytes, which changes the key, which misses.
+//
+// Rejected is a separate flag rather than a non-empty Problem, because the
+// reason is the parser's string and this rule does not get to assume it is
+// non-empty. Inferring rejection from the message would turn a reason-less
+// failure into zero models and no diagnostic — a rejected schema that reads
+// exactly like an empty but passing one.
+type prismaSetOutcome struct {
+  Models   []prismaModel
+  Rejected bool
+  Problem  string
+  // digest is the loader's own, carried out of the bridge answer so the
+  // caller stores under the bytes the loader read rather than the ones this
+  // process read beforehand.
+  digest string
+}
+
+func newPrismaCache() *prismaCache {
+  return &prismaCache{entries: map[string]prismaSetOutcome{}}
+}
+
+type prismaCache struct {
+  mutex   sync.Mutex
+  entries map[string]prismaSetOutcome
+  order   []string
+}
+
+func (cache *prismaCache) lookup(digest string) (prismaSetOutcome, bool) {
+  if digest == "" {
+    return prismaSetOutcome{}, false
+  }
+  cache.mutex.Lock()
+  defer cache.mutex.Unlock()
+  outcome, hit := cache.entries[digest]
+  if !hit {
+    return prismaSetOutcome{}, false
+  }
+  return copyPrismaOutcome(outcome), true
+}
+
+func (cache *prismaCache) store(digest string, outcome prismaSetOutcome) {
+  if digest == "" {
+    return
+  }
+  cache.mutex.Lock()
+  defer cache.mutex.Unlock()
+  if _, exists := cache.entries[digest]; exists {
+    return
+  }
+  if len(cache.order) >= prismaCacheLimit {
+    delete(cache.entries, cache.order[0])
+    cache.order = cache.order[1:]
+  }
+  cache.entries[digest] = copyPrismaOutcome(outcome)
+  cache.order = append(cache.order, digest)
+}
+
+// copyPrismaOutcome deep-copies the models, because a caller builds units from
+// them while another cycle may be reading the same entry.
+func copyPrismaOutcome(outcome prismaSetOutcome) prismaSetOutcome {
+  models := make([]prismaModel, 0, len(outcome.Models))
+  for _, model := range outcome.Models {
+    models = append(models, prismaModel{
+      Name:          model.Name,
+      Documentation: model.Documentation,
+      Fields:        append([]prismaField(nil), model.Fields...),
+    })
+  }
+  return prismaSetOutcome{
+    Models:   models,
+    Rejected: outcome.Rejected,
+    Problem:  outcome.Problem,
+    digest:   outcome.digest,
+  }
+}
+
+// prismaContentDigest composes one key from every file of the ordered set.
+//
+// The composition is the whole cache key, which is what makes staleness
+// structural rather than improbable: identical bytes in identical order parse
+// to identical models, so a hit can only return what the current schema means.
+// The path is folded in beside each file's own hash, so moving a model between
+// two files of one set — which changes nothing about the bytes as a whole —
+// still changes the key, and so does adding or removing a file.
+//
+// An unreadable file yields no digest at all, which keeps the set out of the
+// cache and leaves the loader's own diagnostic for it.
+func prismaContentDigest(root string, sources []string) string {
+  composite := sha256.New()
+  for _, source := range sources {
+    content, err := os.ReadFile(resolveProjectPath(root, source))
+    if err != nil {
+      return ""
+    }
+    file := sha256.Sum256(content)
+    composite.Write([]byte(source))
+    // NUL, matching `SEPARATOR` in the bridge. A path may contain a space
+    // while a hex digest contains nothing outside `[0-9a-f]`, so an
+    // ambiguous separator would let two different sets compose one key.
+    // Spelled as a byte rather than as a literal character for the reason
+    // the bridge records: this separator was once an invisible control
+    // character in one source and a space in the other, and the two hashed
+    // differently with every result still correct.
+    composite.Write([]byte{0})
+    composite.Write([]byte(hex.EncodeToString(file[:])))
+    composite.Write([]byte("\n"))
+  }
+  return hex.EncodeToString(composite.Sum(nil))
+}
+
+// rememberPrismaSchema records an outcome under the bytes it was produced from,
+// as reported by the process that produced it.
+//
+// The digest is the loader's own, never the one this process took beforehand.
+// The loader opens the files again, in another process, after this one read
+// them — so keying on the earlier digest would let a write landing inside that
+// window bind one schema's models to another schema's bytes, and that entry
+// would answer every later cycle with the wrong schema.
+func rememberPrismaSchema(digest string, outcome prismaSetOutcome) {
+  prismaSchemas.store(digest, outcome)
+}
+
+// prismaUnitsFromOutcome rebuilds the set's units and files them under the
+// schema file each one is written in.
+//
+// Units are rebuilt per cycle rather than remembered, because a unit carries
+// its location while the parsed models do not: what was cached is a property of
+// the schema, not of where its text sits.
+func prismaUnitsFromOutcome(
+  root string,
+  sources []string,
+  inventories map[string]*artifactInventory,
+  outcome prismaSetOutcome,
+) []string {
+  if outcome.Rejected {
+    return []string{failPrismaSet(
+      inventories,
+      sources,
+      prismaNormalizationFailure(outcome.Problem),
+    )}
+  }
+  locations, comments := locatePrismaDeclarations(root, sources)
+  fallback := ""
+  if len(sources) != 0 {
+    fallback = sources[0]
+  }
+  indexed := prismaInventoriesByDisplay(inventories)
+  hosts := map[string]*evidenceUnit{}
+  for _, model := range outcome.Models {
+    for _, unit := range prismaModelUnits(model) {
+      key := joinPrismaIdentity(unit.Identity)
+      location, found := locations[key]
+      if !found {
+        // Locating is subordinate: a name the scan did not find keeps a
+        // file-level location and its full participation in coverage,
+        // because every file of the set matches the globs that selected
+        // it. A missing line costs precision, never an obligation.
+        location = prismaLocation{Path: fallback}
+      }
+      unit.Path = location.Path
+      unit.Line = location.Line
+      hosts[key] = unit
+      for _, inventory := range indexed[unit.Path] {
+        inventory.Units = append(inventory.Units, unit)
+      }
+    }
+  }
+  for _, inventory := range inventories {
+    sortUnits(inventory.Units)
+  }
+  return prismaDeclarationsFromComments(comments, hosts, indexed)
+}
+
+// joinPrismaIdentity renders a unit's identity the way the locator keys one.
+//
+// A Prisma identifier is unicode alphanumeric plus `_` and `-` and can never
+// contain a dot (`psl/schema-ast/src/parser/datamodel.pest`), so joining on one
+// is lossless here — the ambiguity that forces a TypeScript identity to stay
+// segmented does not exist in this grammar.
+func joinPrismaIdentity(identity []string) string {
+  return strings.Join(identity, ".")
+}

package/native/prisma_locator.go

@@ -0,0 +1,417 @@
+package evidence
+
+import (
+  "os"
+  "strings"
+  "unicode"
+)
+
+// prismaLocation is where one declared name is written.
+type prismaLocation struct {
+  Path string
+  Line int
+}
+
+// prismaCommentForm distinguishes the three comment syntaxes Prisma's grammar
+// accepts: line comments carry no citation, and only triple-slash documentation
+// can become an unattached file-level exclusion carrier.
+type prismaCommentForm string
+
+const (
+  prismaDocComment   prismaCommentForm = "doc"
+  prismaLineComment  prismaCommentForm = "line"
+  prismaBlockComment prismaCommentForm = "block"
+)
+
+// prismaCommentRun is one contiguous comment block and the declaration it
+// attaches to.
+//
+// Body preserves the run's own line spacing — a line the run skipped is empty
+// rather than absent — so a tag's offset inside the body is still its offset in
+// the file. Key is the declaration the run documents, empty when it documents
+// nothing unless FileLevel identifies a top-level triple-slash exclusion
+// carrier.
+type prismaCommentRun struct {
+  Form      prismaCommentForm
+  Path      string
+  Line      int
+  Body      string
+  Key       string
+  FileLevel bool
+}
+
+// prismaFileScan is everything one schema file yields to the native side.
+type prismaFileScan struct {
+  Locations map[string]prismaLocation
+  Comments  []prismaCommentRun
+}
+
+// prismaBlockKeywords are the top-level block openers Prisma's grammar accepts.
+//
+// All six are recognized even though only `model`, `view`, and `type` can own a
+// unit, because recognizing a block is how the scan knows when it is *not*
+// inside one. Dropping `datasource` and `generator` would leave their settings
+// looking like members of whatever block was declared before them.
+var prismaBlockKeywords = map[string]bool{
+  "model":      true,
+  "view":       true,
+  "type":       true,
+  "enum":       true,
+  "datasource": true,
+  "generator":  true,
+}
+
+// prismaMemberBlocks are the blocks whose members this graph addresses.
+var prismaMemberBlocks = map[string]bool{
+  "model": true,
+  "view":  true,
+  "type":  true,
+}
+
+// locatePrismaDeclarations finds the line each declared name is written on and
+// the comment runs that document them.
+//
+// This is a locator, not a parser. The names it answers for come from Prisma's
+// own parser, which returns no positions at all, so the only questions asked
+// here are *where* a name is written and *what comment precedes it* — never
+// what exists. A name it fails to find loses a precise line and nothing else,
+// which is what makes a native scan safe on a grammar this rule does not own.
+//
+// Two clauses of that grammar do the structural work
+// (`prisma/prisma-engines`, `psl/schema-ast/src/parser/datamodel.pest`):
+// `field_declaration` terminates at `NEWLINE`, and a block opener is likewise
+// its own line. Measured against the real parser, a field whose attribute
+// arguments span two lines and a single-line `model X { ... }` are both hard
+// errors — so "one declaration, one line" is Prisma's rule, inherited rather
+// than approximated.
+//
+// The first spelling of a name wins. A duplicate name across the set is a
+// schema Prisma itself rejects, so this scan never has to arbitrate one.
+func locatePrismaDeclarations(
+  root string,
+  sources []string,
+) (map[string]prismaLocation, []prismaCommentRun) {
+  locations := map[string]prismaLocation{}
+  comments := []prismaCommentRun{}
+  for _, source := range sources {
+    content, err := os.ReadFile(resolveProjectPath(root, source))
+    if err != nil {
+      continue
+    }
+    scan := scanPrismaFile(source, string(content), locations)
+    comments = append(comments, scan.Comments...)
+  }
+  return locations, comments
+}
+
+// scanPrismaFile walks one file once, recording where names are written and
+// which comment run documents each of them.
+//
+// Attachment reproduces what Prisma itself does with a comment, measured rather
+// than inferred, because the two answers differ in a way no reading of the
+// grammar suggests:
+//
+//   - A run attaches to the next declaration, and an intervening `//` line does
+//     not break it — two `///` lines around one `//` document the same
+//     declaration together.
+//   - At top level a blank line detaches the run entirely; inside a block it
+//     does not. `/// doc` then a blank line then `model Sale` documents
+//     nothing, while the same shape above a field still documents that field.
+//   - A run followed by a block attribute or by the block's closing brace
+//     documents nothing.
+//
+// A run that documents nothing keeps an empty Key rather than being dropped,
+// because a citation written there is a citation that will never be honoured —
+// and this rule reports that rather than letting it pass for a tag that works.
+func scanPrismaFile(
+  source string,
+  content string,
+  locations map[string]prismaLocation,
+) prismaFileScan {
+  scan := prismaFileScan{Locations: locations}
+  record := func(key string, line int) {
+    if key == "" {
+      return
+    }
+    if _, exists := locations[key]; exists {
+      return
+    }
+    locations[key] = prismaLocation{Path: source, Line: line}
+  }
+
+  lines := strings.Split(content, "\n")
+  depth := 0
+  block := ""
+  // addressable separates "this comment documents nothing" from "this comment
+  // documents something this graph cannot cite". An enum, a datasource, and a
+  // generator all take a doc comment and none of them owns a unit, so a
+  // citation there needs the second diagnostic — the first would tell its
+  // author to move a comment that is already exactly where they meant it.
+  addressable := false
+  commented := false
+  pending := []prismaPendingComment{}
+  flush := func(key string) {
+    scan.Comments = append(scan.Comments, prismaCommentRuns(source, pending, key)...)
+    pending = nil
+  }
+  for index, raw := range lines {
+    line := strings.TrimSuffix(raw, "\r")
+    code, comment, form, stillCommented := prismaPartsOf(line, commented)
+    commented = stillCommented
+    trimmed := strings.TrimSpace(code)
+    if comment != "" || form != "" {
+      pending = append(pending, prismaPendingComment{
+        Form:     form,
+        Line:     index + 1,
+        Text:     comment,
+        Trailing: trimmed != "",
+        TopLevel: depth == 0,
+      })
+    }
+    if trimmed == "" {
+      // A blank line ends a top-level run. Inside a block it does not,
+      // which is measured behaviour rather than a simplification.
+      if comment == "" && form == "" && depth == 0 {
+        flush("")
+      }
+      continue
+    }
+    opens := strings.Count(code, "{")
+    closes := strings.Count(code, "}")
+    switch {
+    case depth == 0 && opens != 0:
+      keyword, name, ok := prismaBlockHead(trimmed)
+      block, addressable = "", false
+      if !ok {
+        flush("")
+        break
+      }
+      block = name
+      addressable = prismaMemberBlocks[keyword]
+      if addressable {
+        record(name, index+1)
+      }
+      flush(name)
+    case depth == 1 && block != "":
+      name, ok := prismaMemberName(trimmed)
+      if !ok {
+        // A block attribute or the closing brace. Prisma documents
+        // neither, so a run stopping here documents nothing.
+        flush("")
+        break
+      }
+      if addressable {
+        record(block+"."+name, index+1)
+      }
+      flush(block + "." + name)
+    default:
+      flush("")
+    }
+    depth += opens - closes
+    if depth <= 0 {
+      depth = 0
+      block = ""
+      addressable = false
+    }
+  }
+  flush("")
+  return scan
+}
+
+type prismaPendingComment struct {
+  Form prismaCommentForm
+  Line int
+  Text string
+  // Trailing marks a comment that shared its line with code. Prisma treats
+  // such a comment as the field's trailing comment rather than as
+  // documentation, so it can never document the declaration below it.
+  Trailing bool
+  // TopLevel marks a comment written outside every Prisma block. A detached
+  // documentation run there may carry claim-local exclusions for the file
+  // without becoming part of Prisma's generated schema documentation.
+  TopLevel bool
+}
+
+// prismaCommentRuns groups pending comment lines into one run per form.
+//
+// Only the doc-comment run can carry a citation, so the other two are grouped
+// solely to be reported. Keeping the doc run's body line-aligned is what lets a
+// tag inside it be reported at the line it was written on: a line the run
+// skipped becomes an empty line rather than disappearing.
+func prismaCommentRuns(
+  source string,
+  pending []prismaPendingComment,
+  key string,
+) []prismaCommentRun {
+  if len(pending) == 0 {
+    return nil
+  }
+  runs := []prismaCommentRun{}
+  documenting := []prismaPendingComment{}
+  for _, comment := range pending {
+    // `///` and `/* */` are both documentation to Prisma — measured, both
+    // reach the parser's `documentation` and both are emitted into the
+    // generated client and into prisma-markdown's ERD. Only `//` is
+    // discarded, so only `//` cannot carry a citation.
+    if comment.Form != prismaLineComment && !comment.Trailing {
+      documenting = append(documenting, comment)
+      continue
+    }
+    runs = append(runs, prismaCommentRun{
+      Form: comment.Form,
+      Path: source,
+      Line: comment.Line,
+      Body: comment.Text,
+      Key:  "",
+    })
+  }
+  if len(documenting) != 0 {
+    first := documenting[0].Line
+    body := make([]string, documenting[len(documenting)-1].Line-first+1)
+    fileLevel := key == ""
+    for _, comment := range documenting {
+      body[comment.Line-first] = comment.Text
+      fileLevel =
+        fileLevel &&
+          comment.TopLevel &&
+          comment.Form == prismaDocComment
+    }
+    runs = append(runs, prismaCommentRun{
+      Form:      prismaDocComment,
+      Path:      source,
+      Line:      first,
+      Body:      strings.Join(body, "\n"),
+      Key:       key,
+      FileLevel: fileLevel,
+    })
+  }
+  return runs
+}
+
+// prismaPartsOf splits one line into the code it declares and the comment it
+// carries.
+//
+// String contents are dropped from the code rather than kept, because a brace
+// inside one must not open or close a block — `@default("}")` is a legal field
+// that a naive brace count reads as the end of its model. The comment text is
+// returned rather than discarded, because two of the three forms cannot carry a
+// citation and this rule reports one written there instead of ignoring it.
+func prismaPartsOf(
+  line string,
+  commented bool,
+) (string, string, prismaCommentForm, bool) {
+  var code strings.Builder
+  var comment strings.Builder
+  form := prismaCommentForm("")
+  if commented {
+    form = prismaBlockComment
+  }
+  runes := []rune(line)
+  quoted := false
+  for index := 0; index < len(runes); index++ {
+    char := runes[index]
+    if commented {
+      if char == '*' && index+1 < len(runes) && runes[index+1] == '/' {
+        commented = false
+        index++
+        continue
+      }
+      comment.WriteRune(char)
+      continue
+    }
+    if quoted {
+      if char == '\\' {
+        index++
+        continue
+      }
+      if char == '"' {
+        quoted = false
+      }
+      continue
+    }
+    if char == '"' {
+      quoted = true
+      continue
+    }
+    if char == '/' && index+1 < len(runes) && runes[index+1] == '/' {
+      // A third slash makes it a doc comment; a fourth is content, which
+      // is what Prisma's `(!"///") ~ "//"` lookahead decides.
+      rest := index + 2
+      if rest < len(runes) && runes[rest] == '/' {
+        if form == "" {
+          form = prismaDocComment
+        }
+        rest++
+      } else if form == "" {
+        form = prismaLineComment
+      }
+      comment.WriteString(strings.TrimSpace(string(runes[rest:])))
+      break
+    }
+    if char == '/' && index+1 < len(runes) && runes[index+1] == '*' {
+      commented = true
+      if form == "" {
+        form = prismaBlockComment
+      }
+      index++
+      continue
+    }
+    code.WriteRune(char)
+  }
+  return code.String(), strings.TrimSpace(comment.String()), form, commented
+}
+
+// prismaBlockHead reads `model <Name>` from a block opener.
+func prismaBlockHead(trimmed string) (string, string, bool) {
+  fields := strings.Fields(trimmed)
+  if len(fields) < 2 {
+    return "", "", false
+  }
+  if !prismaBlockKeywords[fields[0]] {
+    return "", "", false
+  }
+  name := strings.TrimSuffix(fields[1], "{")
+  if !isPrismaIdentifier(name) {
+    return "", "", false
+  }
+  return fields[0], name, true
+}
+
+// prismaMemberName reads the field name a member line opens with.
+//
+// A line opening with `@` is a block attribute such as `@@index([a, b])` rather
+// than a field, and a line opening with `}` closes the block. Neither declares
+// a member, and both would otherwise be read as one named `@@index` or `}`.
+func prismaMemberName(trimmed string) (string, bool) {
+  if strings.HasPrefix(trimmed, "@") || strings.HasPrefix(trimmed, "}") {
+    return "", false
+  }
+  fields := strings.Fields(trimmed)
+  if len(fields) == 0 {
+    return "", false
+  }
+  if !isPrismaIdentifier(fields[0]) {
+    return "", false
+  }
+  return fields[0], true
+}
+
+// isPrismaIdentifier mirrors the grammar's `identifier` rule: unicode
+// alphanumeric, then unicode alphanumeric or `_` or `-`. No dot can appear in
+// one, which is what lets a member address join on a dot without ambiguity.
+func isPrismaIdentifier(value string) bool {
+  if value == "" {
+    return false
+  }
+  for index, char := range value {
+    switch {
+    case unicode.IsLetter(char), unicode.IsDigit(char):
+      continue
+    case index != 0 && (char == '_' || char == '-'):
+      continue
+    default:
+      return false
+    }
+  }
+  return true
+}