@ttsc/evidence 0.28.6 → 0.30.0

package/lib/structures/ITtscEvidenceGraphClaimBase.d.ts

@@ -1,3 +1,4 @@
+import type { TtscLintSeverity } from "@ttsc/lint";
 import type { ITtscEvidenceGraphReference } from "./ITtscEvidenceGraphReference";
 /**
  * What every claim declares: which artifact kind makes the claim, where its
@@ -21,6 +22,12 @@ export interface ITtscEvidenceGraphClaimBase<Type extends string> {
      * configuration entries.
      */
     name?: string;
+    /**
+     * Diagnostic level for this claim. Omit it or use `undefined` to inherit the
+     * outer `evidence/graph` rule level. A reference may override this level
+     * again. `"off"` disables the entire claim, including its references.
+     */
+    severity?: TtscLintSeverity | undefined;
     /**
      * Excludes this claim from graph loading and evaluation.
      *

package/lib/structures/ITtscEvidenceGraphReferenceBase.d.ts

@@ -1,3 +1,4 @@
+import type { TtscLintSeverity } from "@ttsc/lint";
 /**
  * What every evidence population declares: which artifact kind it materializes,
  * and how strictly the owning claim must acknowledge it.
@@ -25,6 +26,12 @@
 export interface ITtscEvidenceGraphReferenceBase<Type extends string> {
     /** Identifies the artifact kind this population materializes. */
     type: Type;
+    /**
+     * Diagnostic level for this reference's obligation. Omit it or use
+     * `undefined` to inherit the claim level, then the outer `evidence/graph`
+     * rule level. `"off"` disables this reference's population and obligation.
+     */
+    severity?: TtscLintSeverity | undefined;
     /**
      * Whether this reference refuses `@evidenceExclude` as an acknowledgement.
      *

package/lib/structures/ITtscEvidenceGraphTypeScriptReference.d.ts

@@ -13,13 +13,25 @@ import type { ITtscEvidenceGraphReferenceBase } from "./ITtscEvidenceGraphRefere
  * contracts deserve documentary proof.
  */
 export interface ITtscEvidenceGraphTypeScriptReference extends ITtscEvidenceGraphReferenceBase<"typescript"> {
+    /**
+     * Explicit directory whose TypeScript exports are read from disk.
+     *
+     * Resolves relative to the lint project's root, or accepts an absolute path.
+     * Files patterns select entry modules relative to this directory. Their
+     * re-exports must remain inside it. Active Program sources take precedence
+     * over disk snapshots. The directory is watched for changes and new files.
+     *
+     * Cannot combine with package. Omit both to select only the active Program.
+     * File-qualified citation paths remain relative to the citing file.
+     */
+    root?: string;
     /**
      * Installed package whose declarations form this population.
      *
-     * Omit it to select the active project. When present, {@link files} resolves
-     * against the package root instead of the project root, so the globs read as
-     * a consumer thinks of the package rather than carrying its `node_modules`
-     * location.
+     * Omit it to select the active project or the explicit {@link root}. When
+     * present, {@link files} resolves against the package root instead of the
+     * project root, so the globs read as a consumer thinks of the package rather
+     * than carrying its `node_modules` location.
      *
      * A package population is read from disk rather than from the `ttsc` program.
      * That is the point: a symbol nothing imports is absent from the program by
@@ -39,8 +51,8 @@ export interface ITtscEvidenceGraphTypeScriptReference extends ITtscEvidenceGrap
      * `ttsc` project. A matching file outside the project's `tsconfig` program is
      * not available to the rule and does not count as a match.
      *
-     * When {@link package} is set these are package-relative instead, and the
-     * files are read from disk rather than from the program.
+     * With {@link root} or {@link package}, these are relative to that directory or
+     * package and entry files can be read from disk outside the Program.
      *
      * These are globs, not regular expressions. `*` matches within one path
      * segment, `**` crosses any number of path segments, and `?` matches one

package/lib/typings/TtscEvidenceGraphTypeScriptSymbol.d.ts

@@ -58,8 +58,9 @@
  * prepend their namespace, such as `Orders.create`. A namespace itself uses its
  * qualified name, such as `Orders` or `Outer.Inner`. A local declaration
  * 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
+ * default declaration or default alias is publicly addressed as `default`;
+ * anonymous default classes and functions also have that stable address. A
+ * default-only local binding is not a named export. Members of an ambient
  * 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,
@@ -79,17 +80,15 @@
  * 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.
+ * when their expression is a literal. File-qualified accessors use bracketed
+ * JSON strings for literal names, including spaces and dots. Existing inline
+ * links keep their dotted spelling and report ambiguous literal qualification.
  *
- * These targets deliberately omit file paths. If selected files expose the same
- * qualified target, a declaration using that target is ambiguous; rename or
- * further qualify the public symbols. A re-export whose declaration lives in
- * another file does not create a second unit in the barrel file. TypeScript
- * target characters are matched exactly; Markdown path-separator normalization
- * does not rewrite literal symbol names.
+ * A code citation identifies its module through a file path or the citing
+ * TypeScript module's imports. A re-export whose declaration lives in another
+ * file does not create a second unit in the barrel file. TypeScript target
+ * characters are matched exactly; Markdown path-separator normalization does
+ * not rewrite literal symbol names.
  *
  * Every supported public declaration described here may carry
  * `@evidenceExclude` when its file belongs to a claim, even when that claim's

package/native/config.go

@@ -8,6 +8,8 @@ import (
   "path"
   "sort"
   "strings"
+
+  "github.com/samchon/ttsc/packages/lint/rule"
 )
 
 func decodeGraphConfig(raw json.RawMessage) (graphConfig, []string) {
@@ -54,7 +56,7 @@ func decodeClaim(raw json.RawMessage, index int) (claimSpec, []string) {
   }
   problems := rejectUnknownFields(
     object,
-    []string{"type", "name", "disabled", "root", "files", "evidenceExcludeCarriers", "symbol", "reference"},
+    []string{"type", "name", "severity", "disabled", "root", "files", "evidenceExcludeCarriers", "symbol", "reference"},
     graphRuleName,
     path,
   )
@@ -78,6 +80,8 @@ func decodeClaim(raw json.RawMessage, index int) (claimSpec, []string) {
       problems = append(problems, "Invalid evidence/graph configuration at "+path+".disabled: expected a boolean.")
     }
   }
+  severity, severityProblems := decodeGraphSeverity(object["severity"], path+".severity")
+  problems = append(problems, severityProblems...)
   root, rootProblems := decodeClaimRoot(object["root"], kind, path+".root")
   problems = append(problems, rootProblems...)
   files, fileProblems := decodeFiles(object["files"], path+".files")
@@ -98,6 +102,7 @@ func decodeClaim(raw json.RawMessage, index int) (claimSpec, []string) {
   }
   return claimSpec{
     Index:             index,
+    Severity:          severity,
     Type:              kind,
     Name:              name,
     Disabled:          disabled,
@@ -109,16 +114,26 @@ func decodeClaim(raw json.RawMessage, index int) (claimSpec, []string) {
   }, nil
 }
 
-// enabledGraphConfig removes explicitly staged claims after their public
+// enabledGraphConfig removes disabled claims and references after their public
 // configuration has been validated. Keeping the filter separate from decoding
-// preserves original claim indexes and prevents disabled entries from hiding a
+// preserves original indexes and prevents disabled entries from hiding a
 // malformed shape.
 func enabledGraphConfig(config graphConfig) graphConfig {
   claims := make([]claimSpec, 0, len(config.Claims))
   for _, claim := range config.Claims {
-    if claim.Disabled {
+    if claim.Disabled || claim.Severity != nil && *claim.Severity == rule.SeverityOff {
       continue
     }
+    references := make([]referenceSpec, 0, len(claim.References))
+    for _, reference := range claim.References {
+      if reference.Severity == nil || *reference.Severity != rule.SeverityOff {
+        references = append(references, reference)
+      }
+    }
+    if len(references) == 0 {
+      continue
+    }
+    claim.References = references
     claims = append(claims, claim)
   }
   config.Claims = claims
@@ -183,6 +198,7 @@ func decodeReference(
     object,
     []string{
       "type",
+      "severity",
       "noEvidenceExclude",
       "uniqueEvidence",
       "singleEvidencePerSymbol",
@@ -204,6 +220,8 @@ func decodeReference(
   if problem := rejectForeignTypeScriptReference(claimKind, kind, path); problem != "" {
     problems = append(problems, problem)
   }
+  severity, severityProblems := decodeGraphSeverity(object["severity"], path+".severity")
+  problems = append(problems, severityProblems...)
   root, rootProblems := decodeRoot(object["root"], kind, path+".root")
   problems = append(problems, rootProblems...)
   policy, policyProblems := decodeReferencePolicy(object, kind, path)
@@ -265,14 +283,16 @@ func decodeReference(
     return referenceSpec{}, problems
   }
   return referenceSpec{
-    Index:   index,
-    Type:    kind,
-    Policy:  policy,
-    Root:    root,
-    Files:   files,
-    Source:  source,
-    Package: packageName,
-    Symbols: symbols,
+    Severity: severity,
+    Index:    index,
+    Type:     kind,
+    Policy:   policy,
+    Root:     root,
+    Rooted:   kind == artifactTypeScript && object["root"] != nil,
+    Files:    files,
+    Source:   source,
+    Package:  packageName,
+    Symbols:  symbols,
   }, nil
 }
 
@@ -415,24 +435,8 @@ func rejectChecklistConflicts(
   return problems
 }
 
-// rejectForeignTypeScriptReference refuses a code population to a claim that
-// cannot address one.
-//
-// A symbol is cited through an inline link, and that link resolves in the
-// citing module's import scope — which only a TypeScript file has. Every other
-// claim would have to fall back to matching the bare name against one
-// repository-wide table, and that makes symbol-name uniqueness across the whole
-// repository load-bearing: two modules exporting `IPage` make the citation
-// impossible, and the only repair such a diagnostic can offer is renaming
-// production code to suit a lint rule.
-//
-// The check is here rather than at resolution because a configuration error
-// belongs where the configuration is read. Reported once per reference, before
-// any file is opened, instead of once per citation that later fails to resolve.
-//
-// What this gives up is the decision it reverses: documentation can no longer
-// cite code, and the inverse obligation is not the same one. Do not restore the fallback
-// without restoring that record.
+// Code citations require an import scope or the Markdown/TypeScript file-link
+// grammar. Bare repository-wide symbol lookup remains unavailable.
 func rejectForeignTypeScriptReference(
   claimKind artifactKind,
   referenceKind artifactKind,
@@ -440,13 +444,13 @@ func rejectForeignTypeScriptReference(
 ) string {
   if referenceKind != artifactTypeScript ||
     claimKind == artifactTypeScript ||
+    claimKind == artifactMarkdown ||
     claimKind == "" {
     return ""
   }
   return "Invalid evidence/graph configuration at " + path +
-    ".type: only a TypeScript claim can cite TypeScript evidence, because a symbol citation resolves through the citing module's imports and a " +
-    string(claimKind) +
-    " comment has none. Invert the obligation so the code cites this artifact, or move the citation into TypeScript."
+    ".type: TypeScript evidence requires a Markdown or TypeScript claim; a " + string(claimKind) +
+    " claim does not support file-qualified code citations. Move the citation to a supported claim."
 }
 
 // decodeTypeScriptReference reads the two ways a TypeScript population is
@@ -463,6 +467,9 @@ func decodeTypeScriptReference(
   problems := []string{}
   reference := referenceSpec{}
   if raw, exists := object["package"]; exists {
+    if _, rooted := object["root"]; rooted {
+      problems = append(problems, "Invalid evidence/graph configuration at "+path+": 'root' and 'package' select different TypeScript populations and cannot be combined. Choose one base and its 'files' patterns.")
+    }
     var value string
     if err := json.Unmarshal(raw, &value); err != nil {
       problems = append(problems, "Invalid evidence/graph configuration at "+path+".package: expected an installed package name.")
@@ -569,15 +576,8 @@ func decodeClaimRoot(
   return decodePopulationRoot(raw, configPath)
 }
 
-// decodeRoot reads the directory a Markdown or Prisma population resolves
-// against.
-//
-// The property is refused on the two artifact kinds that cannot use it, and
-// each refusal names the channel that artifact does have. A TypeScript
-// population is materialized from the ttsc Program, so a directory outside the
-// project contains no file it could ever reach — `package` is the escape there,
-// and it already exists. A Swagger reference names one exact document, so the
-// location belongs in `file`, where it is visible without a second property.
+// decodeRoot reads a population directory. A TypeScript reference uses its
+// presence to opt into disk loading; Swagger still owns one exact file.
 func decodeRoot(
   raw json.RawMessage,
   kind artifactKind,
@@ -587,11 +587,7 @@ func decodeRoot(
     return "", nil
   }
   switch kind {
-  case artifactMarkdown, artifactPrisma:
-  case artifactTypeScript:
-    return "", []string{
-      "Invalid evidence/graph configuration at " + configPath + ": a TypeScript reference selects the active ttsc program with 'files', or an installed package with 'package'; only a TypeScript claim accepts 'root'.",
-    }
+  case artifactMarkdown, artifactPrisma, artifactTypeScript:
   case artifactSwagger:
     return "", []string{
       "Invalid evidence/graph configuration at " + configPath + ": a Swagger reference owns one exact document; write the ancestor-relative or absolute location in 'file' instead.",

package/native/declaration.go

@@ -35,10 +35,14 @@ func commentHidingTag(comment string) string {
   comment = strings.TrimPrefix(comment, "/**")
   comment = strings.TrimPrefix(comment, "/*")
   comment = strings.TrimSuffix(comment, "*/")
+  fence := commentFence{}
   for _, rawLine := range strings.Split(comment, "\n") {
     line := strings.TrimSpace(rawLine)
     line = strings.TrimSpace(strings.TrimPrefix(line, "*"))
     line = strings.TrimSpace(strings.TrimPrefix(line, "///"))
+    if fence.consume(line) {
+      continue
+    }
     for _, tag := range hiddenDeclarationTags {
       if line != tag && !strings.HasPrefix(line, tag+" ") {
         continue
@@ -75,6 +79,7 @@ func parseCommentDeclarations(
     lineOffset int
   }
   var pending *pendingDeclaration
+  fence := commentFence{}
   parsed := []parsedDeclaration{}
   flush := func() {
     if pending == nil {
@@ -92,6 +97,12 @@ func parseCommentDeclarations(
   for index, rawLine := range lines {
     line := strings.TrimSpace(rawLine)
     line = strings.TrimSpace(strings.TrimPrefix(line, "*"))
+    if fence.consume(line) {
+      if pending != nil {
+        pending.body = append(pending.body, line)
+      }
+      continue
+    }
     tag, body, found := declarationLine(line)
     if found {
       flush()
@@ -136,6 +147,7 @@ func declarationLine(line string) (tagKind, string, bool) {
   }{
     {marker: "@evidenceExclude", tag: tagExclude},
     {marker: "@evidence", tag: tagEvidence},
+    {marker: "@link", tag: tagEvidence},
   } {
     if !strings.HasPrefix(line, candidate.marker) {
       continue
@@ -144,7 +156,11 @@ func declarationLine(line string) (tagKind, string, bool) {
     if remainder != "" && remainder[0] != ' ' && remainder[0] != '\t' {
       continue
     }
-    return candidate.tag, strings.TrimSpace(remainder), true
+    body := strings.TrimSpace(remainder)
+    if candidate.marker == "@link" {
+      body = fileLinkPrefix + body
+    }
+    return candidate.tag, body, true
   }
   return "", "", false
 }
@@ -161,6 +177,9 @@ func splitDeclarationBody(body string) (string, string) {
   if body == "" {
     return "", ""
   }
+  if target, reason, found := splitFileLinkBody(body); found {
+    return target, reason
+  }
   if target, reason, found := splitInlineLinkBody(body); found {
     return target, reason
   }
@@ -221,6 +240,9 @@ func inlineLinkTarget(target string) string {
 
 // displayTarget renders a target the way its author wrote it.
 func displayTarget(target string) string {
+  if isFileLinkTarget(target) {
+    return strings.TrimPrefix(target, fileLinkPrefix)
+  }
   if isInlineLinkTarget(target) {
     return "{@link " + inlineLinkTarget(target) + "}"
   }
@@ -315,6 +337,7 @@ func parseReviews(comment string) []parsedReview {
   comment = strings.TrimSuffix(comment, "*/")
   reviews := []parsedReview{}
   var pending *parsedReview
+  fence := commentFence{}
   var body []string
   flush := func() {
     if pending == nil {
@@ -333,6 +356,12 @@ func parseReviews(comment string) []parsedReview {
     line := strings.TrimSpace(rawLine)
     line = strings.TrimSpace(strings.TrimPrefix(line, "*"))
     line = strings.TrimSpace(strings.TrimPrefix(line, "///"))
+    if fence.consume(line) {
+      if pending != nil {
+        body = append(body, line)
+      }
+      continue
+    }
     if reviews, remainder, opened := reviewLine(line); opened {
       flush()
       pending = &parsedReview{
@@ -442,6 +471,26 @@ func containsWhitespace(value string) bool {
   return false
 }
 
+// Fences inside documentation are examples, not declarations. Their text is
+// still retained when it belongs to a pending reason or review description.
+type commentFence struct {
+  marker rune
+  length int
+}
+
+func (fence *commentFence) consume(line string) bool {
+  marker, length, remainder, opened := markdownFence(line)
+  if opened {
+    if fence.marker == 0 {
+      fence.marker, fence.length = marker, length
+    } else if marker == fence.marker && length >= fence.length && strings.TrimSpace(remainder) == "" {
+      fence.marker, fence.length = 0, 0
+    }
+    return true
+  }
+  return fence.marker != 0
+}
+
 func lineAt(content string, offset int) int {
   if offset < 0 {
     return 1

package/native/default_exports.go

@@ -0,0 +1,62 @@
+package evidence
+
+import shimast "github.com/microsoft/typescript-go/shim/ast"
+
+// Default aliases retain the named declaration's identity. Anonymous class
+// and function declarations own the module's default identity directly.
+func typeScriptDeclarationName(node *shimast.Node) string {
+  if node == nil {
+    return ""
+  }
+  if name := declarationName(node.Name()); name != "" {
+    return name
+  }
+  if isDefaultExported(node) {
+    return "default"
+  }
+  return ""
+}
+
+func collectDefaultExportBindings(statements *shimast.NodeList) map[string]exportedName {
+  bindings := map[string]exportedName{}
+  if statements == nil {
+    return bindings
+  }
+  for _, statement := range statements.Nodes {
+    if statement == nil {
+      continue
+    }
+    if statement.Kind == shimast.KindExportAssignment {
+      assignment := statement.AsExportAssignment()
+      expression := assignment.Expression
+      if !assignment.IsExportEquals && expression != nil && expression.Kind == shimast.KindIdentifier {
+        local := declarationName(expression)
+        bindings[local] = exportedName{Public: local}
+      }
+    }
+    if statement.Kind != shimast.KindExportDeclaration {
+      continue
+    }
+    declaration := statement.AsExportDeclaration()
+    if declaration.ModuleSpecifier != nil || declaration.ExportClause == nil || declaration.ExportClause.Kind != shimast.KindNamedExports {
+      continue
+    }
+    for _, element := range declaration.ExportClause.AsNamedExports().Elements.Nodes {
+      specifier := element.AsExportSpecifier()
+      if declarationName(specifier.Name()) != "default" {
+        continue
+      }
+      local := specifier.PropertyName
+      if local == nil {
+        local = specifier.Name()
+      }
+      name := declarationName(local)
+      typeOnly := declaration.IsTypeOnly || specifier.IsTypeOnly
+      if previous, exists := bindings[name]; exists {
+        typeOnly = typeOnly && previous.TypeOnly
+      }
+      bindings[name] = exportedName{Public: name, TypeOnly: typeOnly}
+    }
+  }
+  return bindings
+}