@ttsc/graph 0.30.4 → 0.31.0

package/lib/model/loadGraph.js

@@ -40,8 +40,8 @@ exports.DUMP_SCHEMA_VERSION = void 0;
 exports.loadGraph = loadGraph;
 exports.parseDump = parseDump;
 const _assertGuard_1 = __importStar(require("typia/lib/internal/_assertGuard"));
-const node_child_process_1 = require("node:child_process");
 const typia_1 = __importDefault(require("typia"));
+const GraphProcessTrace_1 = require("../internal/GraphProcessTrace");
 const nativeExecutable_1 = require("../nativeExecutable");
 const resolveGraphBinary_1 = require("../resolveGraphBinary");
 const TtscGraphMemory_1 = require("./TtscGraphMemory");
@@ -50,21 +50,12 @@ const publishedArtifacts_1 = require("./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.
  */
 exports.DUMP_SCHEMA_VERSION = 8;
 /**
@@ -76,6 +67,15 @@ exports.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.
  */
 function loadGraph(options = {}) {
     const cwd = options.cwd ?? process.cwd();
@@ -102,7 +102,7 @@ function loadGraph(options = {}) {
         // 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 = (0, publishedArtifacts_1.publishArtifacts)({ cwd, tsconfig });
-        result = (0, node_child_process_1.spawnSync)(binary, [
+        result = GraphProcessTrace_1.GraphProcessTrace.spawnSync(binary, [
             "dump",
             "--cwd",
             cwd,
@@ -139,6 +139,15 @@ function loadGraph(options = {}) {
  * 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.
  */
 function parseDump(json) {
     let value;

package/lib/model/loadGraph.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadGraph.js","sourceRoot":"","sources":["../../src/model/loadGraph.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loadGraph.js","sourceRoot":"","sources":["../../src/model/loadGraph.ts"],"names":[],"mappings":"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"}

package/lib/model/publishedArtifacts.d.ts

@@ -1,86 +1,23 @@
-import { type ITtscCapabilityPlugin } from "ttsc";
+import { type CapabilityPluginResolver, type ITtscCapabilityPlugin } from "ttsc";
+import type { IArtifactDirectory } from "./IArtifactDirectory";
+import type { IArtifactInputs } from "./IArtifactInputs";
+import type { IPublishedArtifacts } from "./IPublishedArtifacts";
+import type { IPublishedArtifactsResident } from "./IPublishedArtifactsResident";
 import { TtscLintDaemon } from "./TtscLintDaemon";
 /**
- * Ask the project's `@ttsc/lint` for the artifacts a citation can name, and
- * write them where `ttscgraph dump --artifacts` reads them.
+ * Discover configured publishers and synchronously publish their artifact set.
+ * Input identity is captured before the graph-nodes verbs to avoid accepting a
+ * concurrent document edit as already represented by an older answer.
  *
- * A project that configures no such plugin gets `file: null`, which is the
- * common case and not an error: the graph it produces is the graph it produced
- * before this existed, and the dump says so by not claiming the capability.
- *
- * ## Why this runs here and not in the compiler host
- *
- * The addresses a citation names — a Markdown anchor, `prisma:Sale.price`,
- * `POST:/orders` — are produced by parsers that live in the rule that owns
- * them, and re-deriving any of them in the graph producer would be a second
- * implementation of a published contract. So the units have to arrive from the
- * rule.
- *
- * They cannot arrive in-process. `ttscgraph` is the shipped per-platform
- * binary, never a per-project native host, so it can never have a linked
- * plugin; and `packages/lint` is its own Go module that deliberately carries no
- * requirement on the compiler host. What is left is the channel the host
- * already has: a plugin declares a capability and its sidecar answers a verb,
- * exactly as `lsp-hints` does. `resolveCapabilityPlugins` is what builds and
- * locates those sidecars, and it is the seam `ttscserver` already uses for
- * `capabilities.lsp`, published so a consumer outside the compiler can ask
- * too.
- *
- * Nothing here knows what `@ttsc/evidence` is. It asks a lint install for
- * whatever its configured rules published, and a project that configured none
- * gets an empty answer.
+ * @evidence contracts/common.md#principled-implementation Capability discovery and each sidecar's project-inputs/graph-nodes verbs remain the authorities for plugin selection and artifact meaning.
+ * @evidence contracts/common.md#clear-and-simple-design The one-shot path composes discovery, input capture and publication through helpers also used by resident requests.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unavailable sidecars do not produce fabricated artifacts; no evidence-rule-specific parser or private compiler mutation substitutes for the publisher.
+ * @evidence contracts/common.md#meaningful-documentation Native prose documents synchronous ownership and the freshness snapshot's required ordering.
+ * @evidence contracts/performance.md#efficient-algorithms Discovery runs once per publication, distinct input paths are merged and fingerprinted once, and publisher JSON is concatenated in one pass.
+ * @evidence contracts/performance.md#reuse-equivalent-work This one-shot caller has no resident sidecar owner; resident consumers use publishArtifactsResident and session freshness reuse instead of repeatedly spawning this path.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources SpawnSync owns each child through completion; the exchange file is overwritten per process/project, but historical project files have no explicit reclamation yet.
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths and temporary storage use Node path/os APIs; sidecars receive argument arrays and hidden Windows child windows without shell composition.
  */
-export interface IPublishedArtifacts {
-    /**
-     * Path to the JSON the native producer reads, or `null` when no configured
-     * plugin publishes one.
-     *
-     * `null` is a state rather than an absence, which is why it still carries
-     * {@link inputs}. A project that adds an evidence plugin while a session is
-     * running would otherwise never be reconsidered: nothing would be watched, so
-     * nothing could report that the answer had changed from "none" to "some".
-     */
-    file: string | null;
-    /**
-     * Everything the answer was derived from, as paths this process can state for
-     * itself.
-     *
-     * The artifacts describe documents the compiler's Program never read, so a
-     * source edit does not move them and a document edit does not move the code
-     * graph. Refreshing them is therefore a second invalidation with its own
-     * inputs, and these are those inputs.
-     */
-    inputs: IArtifactInputs;
-    /**
-     * The state of {@link inputs} when the answer was produced.
-     *
-     * Compared against a freshly taken one to decide whether the answer is stale.
-     * When it moved, nothing else in the session can tell: the compiler's own
-     * invalidation watches the build universe, and none of this is in it.
-     */
-    fingerprint: string;
-}
-/** Paths an answer was derived from, split by how they are watched. */
-export interface IArtifactInputs {
-    /** Files stated one by one. */
-    files: string[];
-    /** Directories walked, which is what notices an added or deleted file. */
-    directories: IArtifactDirectory[];
-}
-/** A directory watched on behalf of the pattern that named it. */
-export interface IArtifactDirectory {
-    /** Absolute path of the directory to walk. */
-    path: string;
-    /**
-     * Whether the walk descends.
-     *
-     * Taken from the pattern rather than assumed, because assuming it is
-     * expensive in exactly the case that looks harmless: a rule declaring `*.md`
-     * has the project root for its fixed prefix, and treating that as recursive
-     * would state every file in the repository before every graph request.
-     */
-    recursive: boolean;
-}
 export declare function publishArtifacts(options: {
     cwd: string;
     tsconfig: string;
@@ -98,26 +35,55 @@ export declare function publishArtifacts(options: {
  * so the answer is the same one either way and only its cost differs. The
  * fallback matters more here than most: a daemon that quietly answered nothing
  * would be indistinguishable from a project that publishes nothing.
+ *
+ * @evidence contracts/common.md#principled-implementation Both paths ask the same configured sidecar verbs; input identity is captured before publication and invalidation clears the daemon's stale Program first.
+ * @evidence contracts/common.md#clear-and-simple-design The caller supplies daemon and asynchronous resolver ownership while this function owns ordered input and artifact phases and the shared result assembly.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A failed daemon falls back to the public direct verb, not an invented empty-success result or a reimplementation of its parser.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains resident reuse, direct-command fallback and the reason to invalidate the Program before input collection.
+ * @evidence contracts/performance.md#efficient-algorithms Independent publishers run concurrently within each of two ordered phases; deduplication avoids repeatedly hashing the same declared file path.
+ * @evidence contracts/performance.md#reuse-equivalent-work Session-owned daemons reuse process and plugin loading only while binary, manifest and project context match; changed inputs rebuild the publication.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources The session owns the resolver and daemons. Failed publication joins every selected verb and releases its proof; successful publication transfers proof release to the session. Cancellation closes and joins an active daemon or supervised direct command. One exchange file per process/project still has no historical-file reclamation.
+ * @evidence contracts/portability.md#os-neutral-implementation The fallback preserves native argument-vector invocation and Node path resolution; daemon ownership uses the same cross-platform process boundary.
  */
 export declare function publishArtifactsResident(options: {
     cwd: string;
     tsconfig: string;
-}, daemon: (plugin: ITtscCapabilityPlugin) => TtscLintDaemon | undefined): Promise<IPublishedArtifacts>;
+    signal?: AbortSignal;
+}, daemon: (plugin: ITtscCapabilityPlugin) => Pick<TtscLintDaemon, "ask" | "close"> | undefined | Promise<Pick<TtscLintDaemon, "ask" | "close"> | undefined>, resolver: Pick<CapabilityPluginResolver, "resolve" | "runCommand">): Promise<IPublishedArtifactsResident>;
 /**
  * Whether the inputs an answer was derived from have moved since.
  *
- * Answered by stating paths this process already knows, not by asking the
- * plugin again. The question is asked before every graph request in a resident
- * session, and re-running plugin discovery per request would cost more than the
- * refresh it guards — while a `stat` per document costs less than reading one
- * of them.
+ * Published documents are compared by content identity. The owning resolver
+ * separately qualifies discovery, including successful absence. Unavailable,
+ * incomplete or changed discovery proof requires another lookup.
  *
- * The cost of being wrong in the cheap direction is what makes this worth
- * paying at all: a developer who edited only a spec section, and nothing the
- * compiler reads, otherwise saw the graph keep answering with the headings that
- * section used to have.
+ * @evidence contracts/common.md#principled-implementation The owning discovery query must still qualify this exact lookup, and exchange-file existence plus declared input identity must also hold before any publication or successful absence is reused.
+ * @evidence contracts/common.md#clear-and-simple-design Discovery freshness stays with the resolver and downstream document identity stays with fingerprintInputs; this predicate combines their independent authority.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Equal size and modification time cannot substitute for file-content equivalence, and a partial no-plugin watch list cannot prove discovery stability.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain content-based publication freshness, successful absence and conservative relookup for incomplete discovery proof.
+ * @evidence contracts/performance.md#efficient-algorithms Freshness hashes the distinct declared inputs and traverses watch roots once per inventory entry; its cost grows with watched bytes and entries rather than only stat count.
+ * @evidence contracts/performance.md#reuse-equivalent-work The resolver's original complete discovery proof authorizes sharing populated or empty results; changed or unproved selection requires relookup, and document fingerprints separately qualify overlay reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This predicate borrows an inventory and returns a boolean; the publication and session own their storage and sidecars.
+ * @evidence contracts/portability.md#os-neutral-implementation Existence and fingerprints use Node filesystem APIs and native absolute paths without assumptions about platform shell commands.
  */
 export declare function artifactsAreStale(published: IPublishedArtifacts): boolean;
+/**
+ * Check the exact resident discovery proof before reusing its overlay.
+ * Discovery runs off the request thread; declared artifact bytes remain an
+ * independent freshness premise after that authority has answered.
+ *
+ * @evidence contracts/common.md#principled-implementation The original asynchronous proof must authorize reuse before exchange existence and declared input fingerprints are compared.
+ * @evidence contracts/common.md#clear-and-simple-design Resolver proof and artifact-input validation retain their separate owners in one ordered predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Unavailable or invalid proof requires relookup; no partial inventory substitutes for SDK authority.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes off-thread discovery from this consumer's independent artifact inputs.
+ * @evidence contracts/performance.md#efficient-algorithms The owner validates discovery once and fingerprintInputs hashes each declared file and directory inventory, scaling with declared entries and bytes.
+ * @evidence contracts/performance.md#reuse-equivalent-work Only this exact publication's current proof plus unchanged artifact inputs authorizes reuse, including resolved absence.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This predicate borrows the session-owned publication and acquires no lasting proof or process.
+ * @evidence contracts/portability.md#os-neutral-implementation SDK process observation remains with its owner and artifact checks use Node native filesystem APIs.
+ */
+export declare function artifactsAreStaleResident(published: IPublishedArtifactsResident, options?: {
+    signal?: AbortSignal;
+}): Promise<boolean>;
 /**
  * The directory a declared pattern makes worth walking, or `null` when the
  * pattern names one path and should simply be stated.
@@ -125,18 +91,33 @@ export declare function artifactsAreStale(published: IPublishedArtifacts): boole
  * Two readings have to be right here, and both are cheap to get wrong. A
  * pattern carrying no wildcard is a path, not a tree: watching its parent
  * instead would state every sibling on every request to learn about the one
- * file that was declared. And a pattern that does not say `**` does not descend
- * — treating it as though it did is unbounded in exactly the case that looks
- * harmless, because a bare `*.md` has the project root for its prefix.
+ * file that was declared. A bare filename wildcard stays shallow; globstar or a
+ * wildcard directory component requires descent from the fixed prefix.
+ *
+ * @evidence contracts/common.md#principled-implementation Literal paths remain individual inputs; wildcard paths use their fixed directory prefix and descend when remaining path components can contain matched files.
+ * @evidence contracts/common.md#clear-and-simple-design A single fixed-prefix calculation and descent decision produce the directory descriptor consumed by fingerprinting.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Descent is not inferred solely from globstar, which would miss wildcard directory components followed by a filename.
+ * @evidence contracts/common.md#meaningful-documentation Native prose documents literal paths, bare wildcards and wildcard-directory descent.
+ * @evidence contracts/performance.md#efficient-algorithms Pattern scanning is linear in pattern length and avoids directory traversal at selection time; a bare filename wildcard keeps the walk shallow.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure descriptor calculation has no cross-request producer or validation coordinator; publication owns reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned descriptor transfers to its caller and owns no handle or retained task.
+ * @evidence contracts/portability.md#os-neutral-implementation Both slash forms are recognized at the native-path boundary and relative roots resolve through Node path APIs.
  */
 export declare function watchedBy(pattern: string, cwd: string): IArtifactDirectory | null;
 /**
  * The state of every input, as one comparable string.
  *
- * Files are stated by size and modification time rather than content: this runs
- * before every graph request, and hashing a documentation corpus per request
- * would cost more than the refresh it guards. Directories are walked for the
- * same pair, which is what notices a section added or a document deleted rather
- * than edited.
+ * Files are hashed by content so same-size edits with restored modification
+ * times remain observable. Directory membership is walked conservatively from
+ * declared roots; matching remains the sidecar's responsibility.
+ *
+ * @evidence contracts/common.md#principled-implementation The fingerprint includes input paths and regular-file bytes; sorted records make enumeration order irrelevant while missing paths retain an explicit marker.
+ * @evidence contracts/common.md#clear-and-simple-design File state and conservative directory traversal share one record representation before the final digest.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Metadata equality, hidden-directory skipping and arbitrary depth limits do not stand in for declared input identity.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states content hashing, conservative membership and sidecar ownership of actual matching.
+ * @evidence contracts/performance.md#efficient-algorithms Cost is linear in watched regular-file bytes plus O(N log N) record sorting; broad recursive globs conservatively over-read and may invalidate unrelated edits.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This computes one validation identity; the session compares it with the publication snapshot and decides reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Synchronous reads close their descriptors internally, and the record array exists only for this computation; no historical fingerprint state is retained here.
+ * @evidence contracts/portability.md#os-neutral-implementation Native stat, read and directory APIs handle platform paths; NUL-separated fields prevent filename ambiguity without shell serialization.
  */
 export declare function fingerprintInputs(inputs: IArtifactInputs): string;