@ttsc/graph 0.30.4 → 0.31.0

package/src/model/TtscLintDaemonState.ts

@@ -0,0 +1,174 @@
+import { TtscGraphLinePeer } from "./TtscGraphLinePeer";
+
+/**
+ * FIFO reply correlation and direct-command fallback for one lint daemon.
+ *
+ * Replies have no request id, so admission is serialized. Null means the
+ * resident protocol cannot answer after successful retirement; callers retain
+ * their direct verb fallback. Failed joined shutdown rejects instead.
+ *
+ * @evidence contracts/common.md#principled-implementation Serialized requests and FIFO replies preserve the sidecar protocol; failed and unsupported answers permanently retire this owner.
+ * @evidence contracts/common.md#clear-and-simple-design Line parsing and queue/failure transitions are local; the declared opener owns actual process transport.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Null requests a real direct fallback, never an invented empty result or fake success.
+ * @evidence contracts/common.md#meaningful-documentation Prose explains no-id serialization and the null fallback contract; ask and close document acquisition and retirement.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms ask/close own admission, frame processing and retirement; this declaration groups their retained state.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work ask/close establish continued peer/model reuse, not the class descriptor independently.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources ask/close control acquisition and release; the class declaration adds no separate lifecycle transition.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation queues requests and parses reply lines in memory; the process is reached only through the injected opener's Connection.
+ */
+export class TtscLintDaemonState {
+  private child: TtscGraphLinePeer.Connection | undefined;
+  private readonly pending: ((reply: IReply | null) => void)[] = [];
+  private queue: Promise<unknown> = Promise.resolve();
+  private failed = false;
+  private closing: Promise<void> | undefined;
+
+  public constructor(
+    private readonly open: (
+      events: TtscGraphLinePeer.Events,
+    ) => TtscGraphLinePeer.Connection,
+  ) {}
+
+  /**
+   * Ask one verb and return its raw JSON, or `null` when this daemon cannot
+   * answer it.
+   *
+   * `null` is always "ask the sidecar directly instead", never "the project has
+   * none". The two are indistinguishable downstream — an empty artifact set is
+   * the correct answer for most projects — so a daemon that cannot answer must
+   * never be allowed to look like one that answered nothing.
+   *
+   * Requests are serialized. The daemon answers one line per request in order,
+   * with nothing in the reply to address it by, so a second request in flight
+   * would be matched against the first one's answer.
+   *
+   * @evidence contracts/common.md#principled-implementation A promise queue admits one request at a time because the protocol orders responses without request ids; result text preserves arbitrary JSON values.
+   * @evidence contracts/common.md#clear-and-simple-design ask owns queue admission while send/start/onLine own transport and reply decoding.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Null explicitly requests a direct fallback; it cannot silently masquerade as no published artifacts.
+   * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain null meaning and why requests must be serialized.
+   * @evidence contracts/performance.md#efficient-algorithms Each request writes and decodes one JSON frame; queue work is linear in serialized frame bytes with one active reply.
+   * @evidence contracts/performance.md#reuse-equivalent-work The same target/project sidecar retains process, plugin load and configuration across verbs; invalidate explicitly retires warm Program facts when input generations change.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources The daemon owns one child and reader; close settles pending replies and delegates joined EOF shutdown to the actual adapter, while queued promises remain proportional to submitted caller demand.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation queues one request and parses one reply line; the process is reached only through the injected Connection.
+   */
+  public ask(verb: string, invalidate: boolean): Promise<string | null> {
+    const run = this.queue.then(() => this.send(verb, invalidate));
+    this.queue = run.catch(() => undefined);
+    return run;
+  }
+
+  /**
+   * Stop the sidecar. Safe to call more than once, and after a failure.
+   *
+   * Reply callbacks settle null. Their asks switch to the direct command only
+   * after successful retirement; a shutdown failure propagates to the caller.
+   *
+   * @evidence contracts/common.md#principled-implementation Marking failed before settling requests prevents new daemon work while reader and child ownership are cleared.
+   * @evidence contracts/common.md#clear-and-simple-design One shutdown operation is shared by explicit disposal and transport failure.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Shutdown does not invent a successful reply to unblock a request.
+   * @evidence contracts/common.md#meaningful-documentation Native prose states idempotence, failure safety and the meaning of settled null replies.
+   * @evidence contracts/performance.md#efficient-algorithms Closing visits outstanding reply callbacks once and clears the reader/child references.
+   * @evidence contracts/performance.md#reuse-equivalent-work Closure retires this target's reusable process permanently; later calls return the supported direct-fallback indication.
+   * @evidence contracts/performance.md#bound-retention-and-release-resources Both normal and failed shutdown settle pending callbacks, close readline and end/kill the owned process; the returned completion still joins stdio after process exit and rejects unknown or forced termination.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation settles pending replies and closes the injected Connection; the process work lives there.
+   */
+  public close(): Promise<void> {
+    if (this.closing !== undefined) return this.closing;
+    this.failed = true;
+    for (const settle of this.pending.splice(0)) settle(null);
+    const child = this.child;
+    this.child = undefined;
+    this.closing = Promise.resolve(child?.close(true));
+    void this.closing.catch(() => undefined);
+    return this.closing;
+  }
+
+  private async send(
+    verb: string,
+    invalidate: boolean,
+  ): Promise<string | null> {
+    if (this.failed) {
+      await this.closing;
+      return null;
+    }
+    const child = this.start();
+    if (child === undefined) return null;
+    const reply = await new Promise<IReply | null>((resolve) => {
+      this.pending.push(resolve);
+      child.write(`${JSON.stringify({ invalidate, verb })}\n`, (error) => {
+        if (error === null || error === undefined) return;
+        this.fail();
+      });
+    });
+    if (reply === null || reply.code !== 0) {
+      // A nonzero code is the sidecar declining, and this client cannot tell
+      // "unknown verb" from "the rule failed". Closing rather than retrying
+      // through the daemon is what makes the caller fall back to the direct
+      // command, where a real failure surfaces the same way it always did.
+      await this.close();
+      return null;
+    }
+    return reply.result;
+  }
+
+  private start(): TtscGraphLinePeer.Connection | undefined {
+    if (this.child !== undefined) return this.child;
+    if (this.failed) return undefined;
+    try {
+      this.child = this.open({
+        line: (line) => this.onLine(line),
+        error: () => this.fail(),
+        exit: () => this.fail(),
+      });
+      return this.child;
+    } catch {
+      this.failed = true;
+      return undefined;
+    }
+  }
+
+  private onLine(line: string): void {
+    const settle = this.pending.shift();
+    if (settle === undefined) return;
+    let reply: IReply;
+    try {
+      reply = JSON.parse(line) as IReply;
+    } catch {
+      settle(null);
+      return;
+    }
+    settle(
+      typeof reply.code === "number"
+        ? { code: reply.code, result: rawResult(line) }
+        : null,
+    );
+  }
+
+  private fail(): void {
+    this.close();
+  }
+}
+
+/** One `lsp-serve` reply: a verb result and the code that qualifies it. */
+interface IReply {
+  code: number;
+  result: string;
+}
+
+/**
+ * The `result` member, as the JSON text this daemon's callers parse.
+ *
+ * A verb's result is arbitrary JSON that the caller decodes itself, so it is
+ * handed back as text rather than as a value — which is what the direct command
+ * hands over, and what keeps the two paths interchangeable. The text is
+ * re-serialized rather than sliced out of the line: the bytes are not identical
+ * to the sidecar's own, but the value they decode to is, and no caller here
+ * reads anything else.
+ *
+ * A reply with no `result` is `"null"`, so a caller parses a value either way
+ * instead of being handed the empty string.
+ */
+function rawResult(line: string): string {
+  const parsed = JSON.parse(line) as { result?: unknown };
+  return parsed.result === undefined ? "null" : JSON.stringify(parsed.result);
+}

package/src/model/copyGraphRecords.ts

@@ -0,0 +1,17 @@
+import type { TtscGraphReadonly } from "./TtscGraphReadonly";
+
+/**
+ * Detach frozen graph records into a caller-owned mutable DTO projection.
+ *
+ * @evidence contracts/common.md#principled-implementation structuredClone detaches every nested array and record before restoring the mutable wire DTO type at the ownership transfer.
+ * @evidence contracts/common.md#clear-and-simple-design One inverse ownership operation keeps retained snapshots separate from editable output records.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mutable return type is backed by a detached copy rather than a cast that exposes the retained frozen snapshot.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states that this operation transfers an independent mutable DTO to its caller.
+ * @evidence contracts/performance.md#efficient-algorithms One structured clone copies the requested record population without repeated serialization or field-by-field intermediate copies.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work The store owns continued shard reuse; a mutable output requires independent ownership rather than shared result aliases.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The detached result transfers to the caller and this helper retains no historical copies.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation one structuredClone of in-memory records; no file, path or process is touched.
+ */
+export function copyGraphRecords<T>(value: TtscGraphReadonly<T>): T {
+  return structuredClone(value) as T;
+}

package/src/model/copyGraphSnapshot.ts

@@ -0,0 +1,30 @@
+import type { TtscGraphReadonly } from "./TtscGraphReadonly";
+
+/**
+ * Copy and freeze plain graph DTO records before retaining or exposing them.
+ *
+ * The caller keeps ownership of its input. Graph DTOs contain records, arrays
+ * and primitive values, rather than mutable Map/Set or native handle objects.
+ *
+ * @evidence contracts/common.md#principled-implementation structuredClone detaches nested caller aliases before recursive freezing establishes an immutable owned fact population.
+ * @evidence contracts/common.md#clear-and-simple-design One ownership boundary is shared by model and shard storage rather than separate partial field-copy lists.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Caller-owned objects are never frozen to compensate for a borrowed snapshot alias.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states input ownership and the plain-DTO precondition, avoiding claims about mutable native collections.
+ * @evidence contracts/performance.md#efficient-algorithms One structured clone detaches the population and a WeakSet visits each owned record once during freezing; work and temporary visited storage scale with copied facts.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Model construction and shard transactions decide snapshot reuse; this ownership primitive performs one requested detachment.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Only the detached frozen result transfers to the caller; visited identities are local and no global population is retained.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation one structuredClone and a recursive freeze of in-memory records; no file, path or process is touched.
+ */
+export function copyGraphSnapshot<T>(value: T): TtscGraphReadonly<T> {
+  const owned = structuredClone(value);
+  freezeRecords(owned, new WeakSet<object>());
+  return owned as TtscGraphReadonly<T>;
+}
+
+/** Visit each owned record once, including shared or cyclic references. */
+function freezeRecords(value: unknown, visited: WeakSet<object>): void {
+  if (value === null || typeof value !== "object" || visited.has(value)) return;
+  visited.add(value);
+  for (const child of Object.values(value)) freezeRecords(child, visited);
+  Object.freeze(value);
+}

package/src/model/loadGraph.ts

@@ -1,6 +1,6 @@
-import { spawnSync } from "node:child_process";
 import typia from "typia";
 
+import { GraphProcessTrace } from "../internal/GraphProcessTrace";
 import { captureProcessOutput, ensureExecutable } from "../nativeExecutable";
 import { resolveGraphBinary } from "../resolveGraphBinary";
 import { ITtscGraphDump } from "../structures/ITtscGraphDump";
@@ -11,21 +11,12 @@ import { publishArtifacts } from "./publishedArtifacts";
  * The dump schema version this client reads.
  *
  * Keep it equal to `DumpSchemaVersion` in
- * `packages/ttsc/internal/graph/provenance.go`. The two are hand-synchronized,
- * and `dump_schema_version_matches_the_typescript_client_test.go` reads this
- * constant out of this file and fails if the pair drifts.
+ * `packages/ttsc/internal/graph/provenance.go`. The two are hand-synchronized.
  *
  * Exported because the resident session reads the same dump body over the serve
  * protocol and has to hold it to the same number: the envelope's version and
  * the body's are independent, so a producer can speak this protocol and still
  * send a body from another schema.
- *
- * `scripts/assert-ttscgraph-release-candidate.cjs` reads this declaration out
- * of this file with a regular expression, because it runs against a packaged
- * binary in a workflow that has no reason to have built this package first.
- * Rewriting the declaration — adding a type annotation, splitting the line —
- * makes that script fail loudly rather than silently, and its message names
- * this constant; update its pattern with any such change.
  */
 export const DUMP_SCHEMA_VERSION = 8;
 
@@ -38,13 +29,24 @@ export const DUMP_SCHEMA_VERSION = 8;
  * Throws when the binary cannot be resolved, the dump command fails, or its
  * output is not a readable graph — the server surfaces the failure rather than
  * answering from an empty graph.
+ *
+ * @evidence contracts/common.md#principled-implementation The selected native producer builds the target project and its JSON is schema-version checked and structurally validated before model construction.
+ * @evidence contracts/common.md#clear-and-simple-design One-shot process execution, capture ownership and parse validation have separate helpers; the resident MCP path remains a different lifetime owner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Failed resolution or native execution throws rather than returning an invented empty graph.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs state direct/viewer usage, project/binary defaults and every externally visible failure boundary.
+ * @evidence contracts/portability.md#os-neutral-implementation Native argv carries cwd, tsconfig and artifact paths without a shell; project-anchored binary resolution and permission repair account for host execution differences.
+ * @evidence contracts/performance.md#efficient-algorithms One native dump is followed by linear JSON parsing/validation and model indexing; output is file-backed rather than constrained by a guessed pipe budget.
+ * @evidence contracts/performance.md#reuse-equivalent-work Direct loads intentionally build the requested current project anew; callers needing repeated equivalent snapshots use TtscGraphSession's resident producer and model.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The operation owns two capture descriptors until the finally block disposes them; returned graph ownership transfers to the caller, while artifact storage remains process/project scoped.
  */
 export function loadGraph(
   options: {
     /** Project root the graph is built for (default: `process.cwd()`). */
     cwd?: string;
+
     /** Project tsconfig, relative to `cwd` (default: `tsconfig.json`). */
     tsconfig?: string;
+
     /**
      * Absolute path to the `ttscgraph` binary. Defaults to the per-platform
      * binary resolved from the project's installed `ttsc`; pass it explicitly
@@ -80,7 +82,7 @@ export function loadGraph(
     // into a relation rather than leaving it a token. A project with no lint
     // install, or none that publishes, contributes no file and no claim.
     const artifacts = publishArtifacts({ cwd, tsconfig });
-    result = spawnSync(
+    result = GraphProcessTrace.spawnSync(
       binary,
       [
         "dump",
@@ -126,6 +128,15 @@ export function loadGraph(
  * outlives the process that wrote it — this is the one-shot path, and the JSON
  * on disk may be from any build — so the version is the first question to ask
  * of it.
+ *
+ * @evidence contracts/common.md#principled-implementation Parsing to unknown, reading schema version first and then asserting the full wire type reject mismatched producers before interpreting their shape.
+ * @evidence contracts/common.md#clear-and-simple-design This boundary owns dump decoding and validation for direct loads; model construction remains separate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Malformed JSON and incompatible schemas do not become empty or partially trusted graph facts.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain version-before-shape ordering and why persisted dumps require independent validation.
+ * @evidence contracts/performance.md#efficient-algorithms JSON parsing and shape validation process the dump once before model indexing; cost grows with serialized bytes and graph facts.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This parser validates a supplied exchange string; loadGraph/session own producer sharing and generation identity.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Parsed data transfers to TtscGraphMemory; this operation acquires no native handle or historical cache.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation Parsing serialized graph facts performs no native filesystem or process operation.
  */
 export function parseDump(json: string): ITtscGraphDump {
   let value: unknown;