ttsc 0.27.0 → 0.28.0

package/internal/graph/edge_kinds_names_every_declared_kind_test.go

@@ -0,0 +1,49 @@
+package graph
+
+import (
+  "os"
+  "regexp"
+  "slices"
+  "testing"
+)
+
+// TestEdgeKindsNamesEveryDeclaredKind verifies that EdgeKinds returns exactly the
+// EdgeKind constants this package declares.
+//
+// EdgeKinds exists so a consumer reporting per-kind numbers can seed every family
+// rather than only the ones a particular project contains. That guarantee is only
+// worth having if the list cannot fall behind the constants: a kind added to the
+// block and not to the list is reported as absent rather than as zero, which is
+// the defect the list was introduced to end. Go has no reflection over a const
+// block, so the declarations are read from the source that makes them.
+//
+//  1. Read the EdgeKind constant block from graph.go.
+//  2. Collect every declared wire value.
+//  3. Assert EdgeKinds returns that set, with no extra and no missing member.
+func TestEdgeKindsNamesEveryDeclaredKind(t *testing.T) {
+  source, err := os.ReadFile("graph.go")
+  if err != nil {
+    t.Fatal(err)
+  }
+  matches := regexp.MustCompile(`(?m)^\s*Edge\w+ EdgeKind = "([a-z-]+)"`).
+    FindAllStringSubmatch(string(source), -1)
+  if len(matches) == 0 {
+    t.Fatal("no EdgeKind constant declarations were found in graph.go")
+  }
+
+  declared := make([]string, 0, len(matches))
+  for _, match := range matches {
+    declared = append(declared, match[1])
+  }
+  returned := make([]string, 0, len(EdgeKinds()))
+  for _, kind := range EdgeKinds() {
+    returned = append(returned, string(kind))
+  }
+
+  slices.Sort(declared)
+  slices.Sort(returned)
+  if !slices.Equal(declared, returned) {
+    t.Fatalf("EdgeKinds returns %v, but graph.go declares %v; a kind missing "+
+      "from the list is reported as absent rather than as zero", returned, declared)
+  }
+}

package/internal/graph/edges.go

@@ -31,6 +31,7 @@ func (g *Graph) addEdges(prog *driver.Program, selected map[string]bool, partial
     g.collectHeritage(checker, file)
     g.collectCalls(checker, file)
     g.collectTypeRefs(checker, file)
+    g.collectDocRefs(checker, file)
     g.collectLiterals(checker, file)
     if file.Statements != nil {
       g.collectDecorators(file.FileName(), file.Statements.Nodes)

package/internal/graph/graph.go

@@ -24,6 +24,18 @@ const (
   // imports from. A barrel declares nothing, so this is the only node it has,
   // and it is the node a package.json entry path resolves to.
   NodeModule NodeKind = "module"
+  // The artifact kinds. These are not declarations and they are not this
+  // Program's facts: a plugin materialized them from a Markdown document, a
+  // Prisma schema, or an API document, and the graph indexes what it was handed
+  // without interpreting any of it. Their ids are the address a citation names
+  // rather than the `path#name:kind` grammar, which is why a consumer parsing an
+  // id gates on the kind first.
+  NodeMarkdownDocument NodeKind = "markdown_document"
+  NodeMarkdownSection  NodeKind = "markdown_section"
+  NodePrismaModel      NodeKind = "prisma_model"
+  NodePrismaColumn     NodeKind = "prisma_column"
+  NodePrismaRelation   NodeKind = "prisma_relation"
+  NodeSwaggerOperation NodeKind = "swagger_operation"
 )
 
 // Node is one declared symbol. Its ID is position-invariant, built from the file
@@ -39,10 +51,22 @@ type Node struct {
   // (`"a.b"` → Name `C.a.b`), so the simple/qualified boundary cannot be
   // recovered from Name by splitting on a dot. Recording it here keeps the dump
   // split exact instead of guessing.
-  Simple   string
-  Kind     NodeKind
-  File     string
-  External bool
+  Simple string
+  Kind   NodeKind
+  File   string
+  // ArtifactLine is the 1-based line a published artifact starts on, and is 0
+  // for every declaration — a declaration carries a real span, resolved from the
+  // compiler, and does not need this. It exists because an artifact has no AST
+  // position to take a span from: the plugin that parsed the document reports
+  // where the heading is, and that single number is the whole span an index
+  // carries. The section's content is read from the file when someone needs it,
+  // exactly as a function body is.
+  ArtifactLine int
+  // ArtifactParent is the id of the artifact containing this one — a section's
+  // document or enclosing section, a column's model. Empty for every
+  // declaration, whose containment the TypeScript memory layer synthesizes.
+  ArtifactParent string
+  External       bool
   // Exported marks a node that is part of its module's export surface, resolved
   // through the checker's export table so a re-export (`export { Foo } from`) or
   // a barrel (`export *`) counts, not only an inline `export` modifier. It is
@@ -163,6 +187,19 @@ const (
   // type it mentions (a parameter, return, property, or alias type). It is not a
   // runtime call, so an impact query can filter value edges from type edges.
   EdgeTypeRef EdgeKind = "type-ref"
+  // EdgeDocRef is a reference from a declaration to a symbol its own
+  // documentation names through an inline link. The checker resolves the name
+  // and counts it as a use — an import that exists only to support one survives
+  // `noUnusedLocals` — so the relationship is a compiler fact like every other
+  // edge here, and it was the one class of resolved reference the graph held no
+  // edge for.
+  //
+  // It is its own kind rather than a type-ref because it is not a type
+  // position: a link may name a function, and a consumer filtering type edges
+  // from value edges would be told a documentation mention is one or the other
+  // when it is neither. The tag around the link decides nothing; a link under
+  // `@evidence`, under `@see`, or in ordinary prose is one relation.
+  EdgeDocRef EdgeKind = "doc-ref"
   // EdgeExports runs from a module to a declaration its export table resolves
   // to, through re-exports and barrels. It records which surface a symbol is
   // public on, which the Exported flag cannot: a package's front door and its
@@ -170,6 +207,24 @@ const (
   EdgeExports EdgeKind = "exports"
 )
 
+// EdgeKinds returns every kind Build can put on an edge, in declaration order.
+//
+// A consumer that reports per-kind numbers needs the whole vocabulary rather
+// than the subset a particular project happens to contain: counting only what
+// was seen makes the reported shape depend on the project measured, and a
+// family that dropped to zero disappears instead of reading zero.
+func EdgeKinds() []EdgeKind {
+  return []EdgeKind{
+    EdgeHeritage,
+    EdgeMemberRelation,
+    EdgeValueCall,
+    EdgeValueAccess,
+    EdgeTypeRef,
+    EdgeDocRef,
+    EdgeExports,
+  }
+}
+
 // Edge is a directed, checker-resolved relationship from one node to another,
 // both referenced by Node.ID. File, Pos, and End bound the source expression
 // that produced the edge. File is empty when the From node names it and is set
@@ -204,6 +259,26 @@ type Graph struct {
   // re-parsing source. It is dump-only metadata, separate from Edges so the
   // existing checker-resolved relationships are untouched.
   Decorators []*Decorator
+  // DocTags holds the documentation tags TypeScript does not recognize, written
+  // on the workspace's declarations and captured verbatim so the JSON dump can
+  // attach them to each target node. A convention that attaches a declaration to
+  // something outside the type system — a specification section, an API
+  // operation, a reference document — writes it here and nowhere the graph could
+  // otherwise see. Dump-only metadata, separate from Edges for the same reason
+  // Decorators is.
+  DocTags []*DocTag
+  // docTagPositions deduplicates DocTags by where each tag is written, so a
+  // declaration presented to putDeclaredNode more than once contributes its tags
+  // once. Build-only, like bodyNodes.
+  docTagPositions map[docTagKey]struct{}
+  // docHosts are the declarations the node pass found documentation on, paired
+  // with the node it attributed them to and keyed by their file. The edge pass
+  // resolves documentation links from this set rather than from a walk of its
+  // own, so both halves of a citation cover the same declarations, and it asks
+  // per file so a project's whole documented population is never rescanned for
+  // each one. Build-only.
+  docHosts         map[string][]docHost
+  docHostPositions map[docTagKey]struct{}
   // bodyNodes tracks whether a callable node's display span is the overload
   // implementation rather than an overload signature. It is build-only metadata
   // and intentionally stays out of JSON dumps.

package/internal/graph/provenance.go

@@ -15,7 +15,7 @@ import (
 // field is added, removed, or given a new meaning, independently of the serve
 // envelope's protocol version: a one-shot `ttscgraph dump` written to a file has
 // a schema but never rode the protocol.
-const DumpSchemaVersion = 6
+const DumpSchemaVersion = 8
 
 // The capabilities a snapshot can declare. Each names one class of evidence a
 // consumer may rely on when, and only when, the snapshot lists it.
@@ -26,6 +26,13 @@ const (
   // CapabilitySourceDigests means Sources covers every file the program
   // loaded, each with the digest of the text the checker read.
   CapabilitySourceDigests = "sourceDigests"
+  // CapabilityArtifactNodes means the producer asked the project's configured
+  // plugins for the artifacts a citation can name, so a dump carrying none is a
+  // project that publishes none rather than a producer that never looked. The
+  // two states are otherwise the same absent nodes, and a consumer honouring the
+  // difference is the whole reason a capability is declared rather than
+  // inferred.
+  CapabilityArtifactNodes = "artifactNodes"
   // CapabilityDiskDigests means Sources also carries each file's on-disk
   // digest, so an empty one genuinely means the file could not be read.
   //
@@ -37,6 +44,15 @@ const (
   // CapabilityDiagnostics means Diagnostics is the compiler's complete
   // findings for this generation, as opposed to not having been collected.
   CapabilityDiagnostics = "diagnostics"
+  // CapabilityDocTags means every node carries the documentation tags
+  // TypeScript does not recognize, so an absent `docTags` genuinely means the
+  // declaration carries none.
+  //
+  // It is a separate claim rather than an inference from emptiness for the
+  // reason CapabilityDiskDigests is: a producer built before the field existed
+  // emits nothing, and a consumer reading that as "this declaration cites
+  // nothing" would answer a citation question with a confident, wrong "no".
+  CapabilityDocTags = "docTags"
 )
 
 // Provenance is the snapshot's evidence about the program that produced it.
@@ -67,6 +83,17 @@ type Provenance struct {
   // Producer identifies the binary and the checker behind the facts.
   Producer Producer `json:"producer"`
 
+  // ArtifactProducer identifies the second producer behind the artifact nodes,
+  // and is absent when the dump carries none.
+  //
+  // Every other fact here came from one Program. These did not: a plugin parsed
+  // documents this Program never read, in a process of its own, and saying so is
+  // what keeps the dump's one-generation contract honest instead of letting an
+  // overlay ride the same claim as the compiler's facts. A consumer that must
+  // not mix the two reads this field; one that only answers "what does this
+  // address name" does not care.
+  ArtifactProducer *Producer `json:"artifactProducer,omitempty"`
+
   // Universe fingerprints the inputs that decide which files are in the
   // program at all, as opposed to what is inside them.
   Universe Universe `json:"universe"`
@@ -219,7 +246,7 @@ func TypescriptVersion() string { return shimcore.Version() }
 
 // NewProvenance assembles the evidence for a snapshot while retaining the
 // compiler's physical paths. NewDump projects those paths together with every
-// node, edge, span, and diagnostic through its one cached schema-v6 mapper.
+// node, edge, span, and diagnostic through its one cached path mapper.
 // texts maps a source file's path to the text the checker read (as SourceTexts
 // returns it); disk maps that path to the hex digest of its on-disk bytes, and
 // a path absent from it is reported with an empty Disk. configs and roots come

package/lib/compiler/internal/project/createNativeProjectContextArgs.d.ts

@@ -1,3 +1,12 @@
 import type { ITtscParsedProjectConfig } from "../../../structures/internal/ITtscParsedProjectConfig";
 /** Serialize the retained project identity for a native sidecar invocation. */
 export declare function createNativeProjectContextArgs(project: ITtscParsedProjectConfig, pluginConfigOrigin?: string): string[];
+/**
+ * The identity payload itself, for a caller that spawns a sidecar without going
+ * through the compiler's own argument list.
+ *
+ * Split from the flag so there is still exactly one place that decides what a
+ * sidecar is told about the project. A second caller assembling the same JSON,
+ * or slicing it back out of the flag, is how the two drift.
+ */
+export declare function createNativeProjectContextJson(project: ITtscParsedProjectConfig, pluginConfigOrigin?: string): string;

package/lib/compiler/internal/project/createNativeProjectContextArgs.js

@@ -1,14 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createNativeProjectContextArgs = createNativeProjectContextArgs;
+exports.createNativeProjectContextJson = createNativeProjectContextJson;
 /** Serialize the retained project identity for a native sidecar invocation. */
 function createNativeProjectContextArgs(project, pluginConfigOrigin) {
     return [
         "--project-context-json=" +
-            JSON.stringify({
-                ...project.identity,
-                ...(pluginConfigOrigin === undefined ? {} : { pluginConfigOrigin }),
-            }),
+            createNativeProjectContextJson(project, pluginConfigOrigin),
     ];
 }
+/**
+ * The identity payload itself, for a caller that spawns a sidecar without going
+ * through the compiler's own argument list.
+ *
+ * Split from the flag so there is still exactly one place that decides what a
+ * sidecar is told about the project. A second caller assembling the same JSON,
+ * or slicing it back out of the flag, is how the two drift.
+ */
+function createNativeProjectContextJson(project, pluginConfigOrigin) {
+    return JSON.stringify({
+        ...project.identity,
+        ...(pluginConfigOrigin === undefined ? {} : { pluginConfigOrigin }),
+    });
+}
 //# sourceMappingURL=createNativeProjectContextArgs.js.map

package/lib/compiler/internal/project/createNativeProjectContextArgs.js.map

@@ -1 +1 @@
-{"version":3,"file":"createNativeProjectContextArgs.js","sourceRoot":"","sources":["../../../../src/compiler/internal/project/createNativeProjectContextArgs.ts"],"names":[],"mappings":";;;AAEA,+EAA+E;AAC/E,wCACE,OAAiC,EACjC,kBAA2B;IAE3B,OAAO;QACL,yBAAyB;YACvB,IAAI,CAAC,SAAS,CAAC;gBACb,GAAG,OAAO,CAAC,QAAQ;gBACnB,GAAG,CAAC,kBAAkB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC;aACpE,CAAC;KACL,CAAC;AACJ,CAAC"}
+{"version":3,"file":"createNativeProjectContextArgs.js","sourceRoot":"","sources":["../../../../src/compiler/internal/project/createNativeProjectContextArgs.ts"],"names":[],"mappings":";;;;AAEA,+EAA+E;AAC/E,wCACE,OAAiC,EACjC,kBAA2B;IAE3B,OAAO;QACL,yBAAyB;YACvB,8BAA8B,CAAC,OAAO,EAAE,kBAAkB,CAAC;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,wCACE,OAAiC,EACjC,kBAA2B;IAE3B,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,GAAG,OAAO,CAAC,QAAQ;QACnB,GAAG,CAAC,kBAAkB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC;KACpE,CAAC,CAAC;AACL,CAAC"}

package/lib/index.d.ts

@@ -6,6 +6,7 @@
  * project parsing helpers, and native build helpers stay internal so the public
  * package surface remains small and stable.
  */
+export * from "./plugin/resolveCapabilityPlugins";
 export * from "./TtscCompiler";
 export * from "./TtscService";
 export * from "./structures/index";

package/lib/index.js

@@ -22,6 +22,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./plugin/resolveCapabilityPlugins"), exports);
 __exportStar(require("./TtscCompiler"), exports);
 __exportStar(require("./TtscService"), exports);
 __exportStar(require("./structures/index"), exports);

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;AAEH,iDAA+B;AAC/B,gDAA8B;AAC9B,qDAAmC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;AAEH,oEAAkD;AAClD,iDAA+B;AAC/B,gDAA8B;AAC9B,qDAAmC"}

package/lib/launcher/internal/runtimeHooks.d.ts

@@ -75,8 +75,16 @@ export interface RuntimeHookOptions {
  * `require()` made from inside a CommonJS module that was itself reached
  * through an ESM `import` (the interop translator loads it on the raw CJS
  * path). The ESM graph goes through `registerHooks`; the CommonJS `require`
- * graph goes through `Module._extensions` — the canonical loader extension
- * point `ts-node`/`tsx` use for the same reason.
+ * graph goes through `Module._extensions` and `Module._resolveFilename` — the
+ * canonical loader extension points `ts-node`/`tsx` use for the same reason.
+ *
+ * Both halves of that second graph are required, and they answer different
+ * questions. `_extensions` decides how a file that was _found_ is compiled, and
+ * Node reuses its keys when it probes an extensionless request, so
+ * `require("./x")` reaches `x.ts` for free. Nothing there resolves a request
+ * that already carries an extension: `require("./x.js")` backed only by `x.ts`
+ * is a resolution failure before any compiler is consulted, which is why the
+ * rescue is installed on `_resolveFilename` as well (samchon/ttsc#1280).
  */
 export declare function installRuntimeHooks(options?: RuntimeHookOptions): void;
 /**

package/lib/launcher/internal/runtimeHooks.js

@@ -182,8 +182,16 @@ let prepareRuntimeEntry;
  * `require()` made from inside a CommonJS module that was itself reached
  * through an ESM `import` (the interop translator loads it on the raw CJS
  * path). The ESM graph goes through `registerHooks`; the CommonJS `require`
- * graph goes through `Module._extensions` — the canonical loader extension
- * point `ts-node`/`tsx` use for the same reason.
+ * graph goes through `Module._extensions` and `Module._resolveFilename` — the
+ * canonical loader extension points `ts-node`/`tsx` use for the same reason.
+ *
+ * Both halves of that second graph are required, and they answer different
+ * questions. `_extensions` decides how a file that was _found_ is compiled, and
+ * Node reuses its keys when it probes an extensionless request, so
+ * `require("./x")` reaches `x.ts` for free. Nothing there resolves a request
+ * that already carries an extension: `require("./x.js")` backed only by `x.ts`
+ * is a resolution failure before any compiler is consulted, which is why the
+ * rescue is installed on `_resolveFilename` as well (samchon/ttsc#1280).
  */
 function installRuntimeHooks(options = {}) {
     if (options.prepareEntry !== undefined) {
@@ -203,6 +211,7 @@ function installRuntimeHooks(options = {}) {
     }
     (0, node_module_1.registerHooks)({ load, resolve });
     installCommonJsHook();
+    installCommonJsResolveHook();
 }
 /**
  * Register a CommonJS `require` handler for each TypeScript source extension so
@@ -219,6 +228,88 @@ function installCommonJsHook() {
         extensions[extension] = compile;
     }
 }
+/**
+ * Map a JavaScript spelling back to its TypeScript source on the CommonJS
+ * resolution path, so `require("./x.js")` finds `x.ts` when nothing emitted
+ * `x.js`.
+ *
+ * TypeScript asks authors to write the emitted `.js` extension in a relative
+ * specifier, so this spelling is the documented one rather than a mistake, and
+ * the ESM `resolve` hook has always rescued it. The CommonJS graph could not,
+ * and on Node 22 that graph is reached by every `require()` inside a CommonJS
+ * module the ESM loader evaluated — `module.registerHooks` sees the `import()`
+ * of that module and nothing within it. Node 24 routes the same `require`
+ * through the hooks, which is why the gap was only ever visible on the oldest
+ * runtime ttsx supports (`engines.node` is `>=22.15.0`).
+ *
+ * The wrapper only ever answers a request Node's own resolver already refused,
+ * so a resolution that succeeds is never perturbed, and a request no candidate
+ * satisfies rethrows Node's original error with its `MODULE_NOT_FOUND` code and
+ * `requireStack` intact. `require.resolve` shares this entry point and is
+ * rescued with it, except in its `{ paths }` form, which resolves against the
+ * caller's list rather than the parent this reads.
+ */
+function installCommonJsResolveHook() {
+    const internals = node_module_1.Module;
+    const original = internals._resolveFilename;
+    internals._resolveFilename = function resolveFilename(request, parent, isMain, options) {
+        try {
+            return original.call(this, request, parent, isMain, options);
+        }
+        catch (error) {
+            const rescued = rescueCommonJsRequest(request, parent, options);
+            if (rescued === null) {
+                throw error;
+            }
+            return rescued;
+        }
+    };
+}
+/**
+ * The TypeScript source a refused CommonJS request names, or `null`.
+ *
+ * Only a relative or absolute request can be rescued: a bare specifier is a
+ * package lookup, whose own resolver already probed every extension the
+ * installed `_extensions` keys declare.
+ *
+ * Two shapes decline before that. `_resolveFilename` is an internal entry point
+ * anything may call, so a non-string request reaches here as readily as a
+ * specifier does, and reading it would replace Node's own argument error with a
+ * `TypeError` from this file. And `require.resolve(request, { paths })`
+ * resolves against the caller's list, which this rescue does not consult, so
+ * answering it from the parent's directory would be a different question's
+ * answer.
+ */
+function rescueCommonJsRequest(request, parent, options) {
+    if (typeof request !== "string") {
+        return null;
+    }
+    if (typeof options === "object" &&
+        options !== null &&
+        Array.isArray(options.paths)) {
+        return null;
+    }
+    let base;
+    if (node_path_1.default.isAbsolute(request)) {
+        base = request;
+    }
+    else if (isRelativeSpecifier(request)) {
+        const from = parent?.filename;
+        if (typeof from !== "string") {
+            return null;
+        }
+        base = node_path_1.default.resolve(node_path_1.default.dirname(from), request);
+    }
+    else {
+        return null;
+    }
+    for (const candidate of typescriptSourcesForJavaScriptSpecifier(base)) {
+        if (isFile(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
 /**
  * The module format of the entry source file, derived from the entry project's
  * compiler options (via the runtime manifest) the same way the served files are