ttsc 0.26.2 → 0.28.0

package/cmd/ttscgraph/dump.go

@@ -23,6 +23,11 @@ func runDump(args []string) int {
   cwdFlag := fs.String("cwd", "", "project root (defaults to process cwd)")
   tsconfigFlag := fs.String("tsconfig", "tsconfig.json", "project tsconfig path")
   prettyFlag := fs.Bool("pretty", false, "indent the JSON output")
+  artifactsFlag := fs.String(
+    "artifacts",
+    "",
+    "path to the artifacts a plugin published (JSON); absent or missing means none",
+  )
   if err := fs.Parse(args); err != nil {
     return 2
   }
@@ -37,7 +42,7 @@ func runDump(args []string) int {
     cwd = resolved
   }
   // Resolve the project root the same way LoadProgram does (absolute, then
-  // tsgo-normalized) so the schema-v6 mapper receives the same canonical root
+  // tsgo-normalized) so the dump path mapper receives the same canonical root
   // grammar and drive-letter case as the compiler's source paths.
   if abs, err := filepath.Abs(cwd); err == nil {
     cwd = abs
@@ -57,9 +62,19 @@ func runDump(args []string) int {
   defer func() { _ = prog.Close() }()
 
   g := graph.Build(prog)
+  // The artifacts arrive from a plugin that parsed documents this Program never
+  // read, so they are a second producer's facts and the origin says so. Applying
+  // them before the dump is what turns a citation of a document section from a
+  // token into a relation.
+  artifacts, err := graph.LoadArtifacts(strings.TrimSpace(*artifactsFlag))
+  if err != nil {
+    fmt.Fprintf(stderr, "ttscgraph: could not read the published artifacts: %v\n", err)
+    return 1
+  }
+  graph.ApplyArtifacts(g, artifacts)
   ignored := graph.GitIgnoredFiles(cwd, g)
   texts := graph.SourceTexts(prog)
-  origin, err := dumpOrigin(prog, texts)
+  origin, err := dumpOrigin(prog, texts, strings.TrimSpace(*artifactsFlag) != "")
   if err != nil {
     fmt.Fprintf(stderr, "ttscgraph: %v\n", err)
     return 1
@@ -89,7 +104,16 @@ func runDump(args []string) int {
 // saw the project, so it carries the same provenance a served snapshot does:
 // without it the file is a pile of facts with no way to tell which program, or
 // which day, they describe.
-func dumpOrigin(prog *driver.Program, texts map[string]string) (graph.DumpOrigin, error) {
+// dumpOrigin builds the provenance for one dump. askedForArtifacts is what
+// turns the artifact capability from a guess into a claim: a producer that was
+// never pointed at a publisher did not look, and saying it did would make a
+// project with no artifacts indistinguishable from one whose artifacts were
+// never requested.
+func dumpOrigin(
+  prog *driver.Program,
+  texts map[string]string,
+  askedForArtifacts bool,
+) (graph.DumpOrigin, error) {
   configs, err := parsedConfigs(prog)
   if err != nil {
     return graph.DumpOrigin{}, err
@@ -102,15 +126,23 @@ func dumpOrigin(prog *driver.Program, texts map[string]string) (graph.DumpOrigin
   if err != nil {
     return graph.DumpOrigin{}, err
   }
+  capabilities := fullSnapshotCapabilities
+  if askedForArtifacts {
+    capabilities = append(append([]string{}, capabilities...), graph.CapabilityArtifactNodes)
+  }
+  provenance := graph.NewProvenance(
+    serveProducer(),
+    capabilities,
+    fileDigests(configHashes),
+    rootFileEntries(projectRootFilesFromConfigs(configs, false)),
+    texts,
+    diskDigests,
+  )
+  if askedForArtifacts {
+    provenance.ArtifactProducer = &graph.Producer{Tool: "@ttsc/lint graph-nodes"}
+  }
   return graph.DumpOrigin{
-    Provenance: graph.NewProvenance(
-      serveProducer(),
-      fullSnapshotCapabilities,
-      fileDigests(configHashes),
-      rootFileEntries(projectRootFilesFromConfigs(configs, false)),
-      texts,
-      diskDigests,
-    ),
+    Provenance:  provenance,
     Diagnostics: graph.NewDiagnostics(prog),
   }, nil
 }

package/cmd/ttscgraph/run_dump_claims_artifacts_only_when_it_asked_test.go

@@ -0,0 +1,135 @@
+package main
+
+import (
+  "bytes"
+  "encoding/json"
+  "os"
+  "path/filepath"
+  "slices"
+  "strings"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/graph"
+)
+
+// TestRunDumpClaimsArtifactsOnlyWhenItAsked verifies that the artifact
+// capability is a statement about what this producer did, not about what it
+// found.
+//
+// The two states a consumer must distinguish are "this project publishes no
+// artifacts" and "this producer was never pointed at a publisher". Both are the
+// same absent nodes, so only the claim separates them — and a producer that
+// claimed unconditionally would make a project with no lint install look like a
+// project whose documents cite nothing. The second producer is named for the
+// same reason: these facts did not come from this Program, and the dump's
+// one-generation contract stays honest by saying so rather than by hiding it.
+//
+//  1. Dump a project with no `--artifacts`, and assert neither the claim nor the
+//     second producer appears, and that the citation stays a token.
+//  2. Dump the same project with a published set, and assert both appear and the
+//     citation resolved to a node carrying its heading and its line.
+func TestRunDumpClaimsArtifactsOnlyWhenItAsked(t *testing.T) {
+  root := t.TempDir()
+  writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
+  "compilerOptions": { "target": "ES2022", "module": "commonjs", "strict": true },
+  "files": ["src/main.ts"]
+}
+`)
+  writeGraphFile(t, filepath.Join(root, "src", "main.ts"), `/** @evidence docs/sale.md#pricing States the rule. */
+export function priced(): void {}
+`)
+
+  plain := decodeArtifactDump(t, runDumpForArtifacts(t, root, ""))
+  if slices.Contains(plain.Provenance.Capabilities, graph.CapabilityArtifactNodes) {
+    t.Fatalf("a dump that was never pointed at a publisher claimed %q", graph.CapabilityArtifactNodes)
+  }
+  if plain.Provenance.ArtifactProducer != nil {
+    t.Fatal("a dump with no artifacts named a second producer")
+  }
+  for _, node := range plain.Nodes {
+    if node.ID == "docs/sale.md#pricing" {
+      t.Fatal("an unrequested dump fabricated an artifact node")
+    }
+  }
+
+  published := filepath.Join(root, "artifacts.json")
+  if err := os.WriteFile(published, []byte(`[
+  {"address":"docs/sale.md","kind":"markdown_document","readable":"Sale","file":"docs/sale.md","line":1},
+  {"address":"docs/sale.md#pricing","kind":"markdown_section","readable":"Pricing","parent":"docs/sale.md","file":"docs/sale.md","line":7}
+]`), 0o644); err != nil {
+    t.Fatal(err)
+  }
+
+  indexed := decodeArtifactDump(t, runDumpForArtifacts(t, root, published))
+  if !slices.Contains(indexed.Provenance.Capabilities, graph.CapabilityArtifactNodes) {
+    t.Fatalf("a dump that asked declares %v, missing %q",
+      indexed.Provenance.Capabilities, graph.CapabilityArtifactNodes)
+  }
+  if indexed.Provenance.ArtifactProducer == nil {
+    t.Fatal("the artifact nodes came from another Program and the dump did not say so")
+  }
+
+  var section *graph.DumpNode
+  for index := range indexed.Nodes {
+    if indexed.Nodes[index].ID == "docs/sale.md#pricing" {
+      section = &indexed.Nodes[index]
+    }
+  }
+  if section == nil {
+    t.Fatal("the cited section is not a node")
+  }
+  if section.Name != "Pricing" {
+    t.Fatalf("the section is named %q, not the heading text an index exists to hold", section.Name)
+  }
+  if section.Parent != "docs/sale.md" {
+    t.Fatalf("the section's parent is %q, want its document", section.Parent)
+  }
+  if section.Evidence == nil || section.Evidence.StartLine != 7 {
+    t.Fatalf("the section carries no span at its heading: %+v", section.Evidence)
+  }
+  cited := false
+  for _, edge := range indexed.Edges {
+    if edge.Kind == "doc_ref" && edge.To == "docs/sale.md#pricing" {
+      cited = true
+    }
+  }
+  if !cited {
+    t.Fatal("the citation stayed a token; it has to resolve to the node now that one exists")
+  }
+}
+
+// runDumpForArtifacts runs the dump subcommand and returns its stdout.
+func runDumpForArtifacts(t *testing.T, root, artifacts string) string {
+  t.Helper()
+  args := []string{"dump", "--cwd", root, "--tsconfig", "tsconfig.json"}
+  if artifacts != "" {
+    args = append(args, "--artifacts", artifacts)
+  }
+  var out, errOut bytes.Buffer
+  restoreStdout, restoreStderr := stdout, stderr
+  stdout, stderr = &out, &errOut
+  defer func() { stdout, stderr = restoreStdout, restoreStderr }()
+
+  if code := run(args); code != 0 {
+    t.Fatalf("dump exited %d: %s", code, errOut.String())
+  }
+  return out.String()
+}
+
+type artifactDump struct {
+  Provenance struct {
+    Capabilities     []string        `json:"capabilities"`
+    ArtifactProducer *graph.Producer `json:"artifactProducer"`
+  } `json:"provenance"`
+  Nodes []graph.DumpNode `json:"nodes"`
+  Edges []graph.DumpEdge `json:"edges"`
+}
+
+func decodeArtifactDump(t *testing.T, raw string) artifactDump {
+  t.Helper()
+  var parsed artifactDump
+  if err := json.Unmarshal([]byte(strings.TrimSpace(raw)), &parsed); err != nil {
+    t.Fatalf("dump is not JSON: %v", err)
+  }
+  return parsed
+}

package/cmd/ttscgraph/run_dump_declares_the_capability_its_output_carries_test.go

@@ -0,0 +1,96 @@
+package main
+
+import (
+  "bytes"
+  "encoding/json"
+  "path/filepath"
+  "slices"
+  "strings"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/graph"
+)
+
+// TestRunDumpDeclaresTheCapabilityItsOutputCarries verifies that the shipped
+// `dump` command's own output declares the documentation-tag capability, and
+// that a project carrying no tag emits the field nowhere.
+//
+// The claim is the contract, and it can only be tested where it is made. A test
+// that hands a capability list to the marshaller and reads it back proves the
+// slice was copied; it leaves the production list free to lose the member with
+// nothing failing. That matters because the two states a consumer must
+// distinguish — "this declaration cites nothing" and "this producer never
+// looked" — are the same absent field, so a dump that carries tags and forgets
+// to say so is read as a repository where nothing cites anything.
+//
+//  1. Run the `dump` subcommand over a project with a tag, capturing stdout.
+//  2. Assert the capability is declared and the tag is present in the output.
+//  3. Run it over a project with no tag and assert the field appears nowhere,
+//     while the claim still does.
+func TestRunDumpDeclaresTheCapabilityItsOutputCarries(t *testing.T) {
+  tagged := runDumpForCapabilityProbe(t, `/** @evidence docs/a.md#x Cited. */
+export function subject(): void {}
+`)
+  untagged := runDumpForCapabilityProbe(t, `/** Ordinary documentation. */
+export function subject(): void {}
+`)
+
+  for name, raw := range map[string]string{"tagged": tagged, "untagged": untagged} {
+    var parsed struct {
+      Provenance struct {
+        Capabilities []string `json:"capabilities"`
+      } `json:"provenance"`
+    }
+    if err := json.Unmarshal([]byte(raw), &parsed); err != nil {
+      t.Fatalf("%s dump is not JSON: %v", name, err)
+    }
+    if !slices.Contains(parsed.Provenance.Capabilities, graph.CapabilityDocTags) {
+      t.Fatalf("%s dump declares %v, missing %q; a consumer would then read a "+
+        "tagged declaration as citing nothing",
+        name, parsed.Provenance.Capabilities, graph.CapabilityDocTags)
+    }
+  }
+
+  if !strings.Contains(tagged, `"docs/a.md#x Cited."`) {
+    t.Fatalf("the tagged dump carried no tag text")
+  }
+  // Read the raw document rather than a decoded slice: an absent field and an
+  // empty one decode identically, and absent is what the wire contract says.
+  // The key is matched with its colon, because the capability shares the name
+  // and rides the same document as a bare string.
+  if strings.Contains(untagged, `"docTags":`) {
+    t.Fatalf("the untagged dump carried a docTags field; it must be absent")
+  }
+  if !strings.Contains(tagged, `"docTags":`) {
+    t.Fatalf("the tagged dump carried no docTags field, so the check above proves nothing")
+  }
+}
+
+// runDumpForCapabilityProbe runs the dump subcommand over a one-file project and
+// returns its stdout.
+func runDumpForCapabilityProbe(t *testing.T, source string) string {
+  t.Helper()
+  root := t.TempDir()
+  writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "strict": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "files": ["src/main.ts"]
+}
+`)
+  writeGraphFile(t, filepath.Join(root, "src", "main.ts"), source)
+
+  var out, errOut bytes.Buffer
+  restoreStdout, restoreStderr := stdout, stderr
+  stdout, stderr = &out, &errOut
+  defer func() { stdout, stderr = restoreStdout, restoreStderr }()
+
+  if code := run([]string{"dump", "--cwd", root, "--tsconfig", "tsconfig.json"}); code != 0 {
+    t.Fatalf("dump exited %d: %s", code, errOut.String())
+  }
+  return out.String()
+}