@ttsc/graph 0.30.3 → 0.31.0

package/src/server/pathPolicy.ts

@@ -1,6 +1,20 @@
-import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { TtscGraphReadonly } from "../model/TtscGraphReadonly";
+import { ITtscGraphNode as NodeShape } from "../structures/ITtscGraphNode";
 
-/** True for dependency declarations outside the authored project graph. */
+type ITtscGraphNode = TtscGraphReadonly<NodeShape>;
+
+/**
+ * True for dependency declarations outside the authored project graph.
+ *
+ * @evidence contracts/common.md#principled-implementation Producer external status, bundled coordinates and node_modules path segments identify dependency boundaries in the graph's portable vocabulary.
+ * @evidence contracts/common.md#clear-and-simple-design One predicate owns external selection for projections.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Selection follows provenance and dependency coordinates rather than named repositories.
+ * @evidence contracts/common.md#meaningful-documentation The native headline states dependency-boundary meaning; the predicate uses portable graph coordinates rather than native paths.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one flag read and two string tests on a single coordinate.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation classifies a slash-normalized coordinate string from the dump and never touches the filesystem.
+ */
 export function isExternalNode(node: ITtscGraphNode): boolean {
   return (
     node.external ||
@@ -13,12 +27,35 @@ export function isExternalNode(node: ITtscGraphNode): boolean {
  * True for a `.d.ts` declaration file. Every declaration such a file holds is
  * ambient by construction, so none of them carries a body the graph can walk
  * into, whether or not the `declare` keyword is written out.
+ *
+ * @evidence contracts/common.md#principled-implementation The declaration-file suffix recognizes d.ts, d.cts and d.mts ambient files under TypeScript's supported filename conventions.
+ * @evidence contracts/common.md#clear-and-simple-design One suffix predicate is reused by body and support-file policies.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Ambient status is not guessed from fixture names or missing written declare keywords.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains why ambient declarations are bodyless regardless of modifier spelling.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms one suffix test on a single coordinate.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation tests the suffix of a coordinate string and never touches the filesystem.
  */
 export function isDeclarationFile(file: string): boolean {
   return /\.d\.[cm]?ts$/.test(file);
 }
 
-/** True for tests, examples, fixtures, generated output, and build artifacts. */
+/**
+ * True for conventional tests, examples, fixtures, generated output and builds.
+ *
+ * This is a projection heuristic over portable graph coordinates, not proof
+ * that a source is generated or a package's manifest classification.
+ *
+ * @evidence contracts/common.md#principled-implementation Segment and suffix conventions select likely support material; declaration-file and dependency checks share the established coordinate vocabulary.
+ * @evidence contracts/common.md#clear-and-simple-design One policy combines conventional support categories for rankers rather than duplicating regexes in each runner.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The heuristic uses general path categories and does not hardcode benchmark repositories or expected symbols.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states heuristic status and its provenance limitation rather than certifying generated source from naming.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms a fixed handful of string and pattern tests on a single coordinate.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation classifies a slash-normalized coordinate string from the dump and never touches the filesystem.
+ */
 export function isSupportPath(file: string): boolean {
   return (
     file === "" ||
@@ -34,7 +71,21 @@ export function isSupportPath(file: string): boolean {
   );
 }
 
-/** True for source files whose declarations are tests or test helpers. */
+/**
+ * True for conventional test-directory or test/spec-suffixed source paths.
+ *
+ * This identifies likely test anchors by path convention; it does not execute
+ * tests or establish their behavioral coverage.
+ *
+ * @evidence contracts/common.md#principled-implementation Complete path segments and TypeScript/JavaScript test suffixes recognize conventional test locations without substring matches on arbitrary names.
+ * @evidence contracts/common.md#clear-and-simple-design The test subset has one predicate separate from the broader support-file policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Returned test anchors follow general conventions rather than an expected benchmark answer list.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains conventional selection and its lack of behavioral verification.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms two pattern tests on a single coordinate.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation classifies a slash-normalized coordinate string from the dump and never touches the filesystem.
+ */
 export function isTestPath(file: string): boolean {
   return (
     /(^|\/)(test|tests|__tests__|spec)\//.test(file) ||
@@ -42,7 +93,21 @@ export function isTestPath(file: string): boolean {
   );
 }
 
-/** True when exported symbols are unlikely to be authored public API. */
+/**
+ * True when exported symbols are unlikely to be authored public API.
+ *
+ * Support material, ambient typings and internal directories are selection
+ * signals, not proof that a symbol cannot be imported.
+ *
+ * @evidence contracts/common.md#principled-implementation Shared support selection plus typings/internal conventions identify likely API noise while preserving actual compiler export facts elsewhere.
+ * @evidence contracts/common.md#clear-and-simple-design The API projection adds its own two exclusions to the common support predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Heuristic API visibility does not rewrite the producer's actual export table.
+ * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes likely authored API from supported importability.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a boolean and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms a fixed handful of pattern tests on a single coordinate.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure per-call work with no cache, so there is nothing to share or invalidate.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation classifies a slash-normalized coordinate string from the dump and never touches the filesystem.
+ */
 export function isPublicApiNoisePath(file: string): boolean {
   return (
     isSupportPath(file) ||

package/src/server/resolveHandle.ts

@@ -1,13 +1,12 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
 import { parseTtscGraphNodeId } from "../model/TtscGraphNodeId";
-import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { TtscGraphReadonly } from "../model/TtscGraphReadonly";
+import { ITtscGraphNode as NodeShape } from "../structures/ITtscGraphNode";
+import type { IResolvedGraphHandle } from "./IResolvedGraphHandle";
 import { exportFanIn } from "./exportSurface";
 import { isSupportPath } from "./pathPolicy";
 
-export interface IResolvedGraphHandle {
-  node?: ITtscGraphNode;
-  candidates?: ITtscGraphNode[];
-}
+type ITtscGraphNode = TtscGraphReadonly<NodeShape>;
 
 /**
  * Resolve a tool handle as an id, an exact symbol name, a dotted suffix, or a
@@ -34,6 +33,15 @@ export interface IResolvedGraphHandle {
  *   method (`db.query`, `app.listen`, `repo.save`), so the member is what it
  *   means, and the candidates come back ranked when several classes declare
  *   it.
+ *
+ * @evidence contracts/common.md#principled-implementation Exact id/name resolution precedes suffix and file/member fallbacks; unique outcomes preserve identity while multiple matches remain candidates.
+ * @evidence contracts/common.md#clear-and-simple-design Resolution helpers each own one handle form and one shared ranker orders ambiguity consistently.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts General handle grammar and compiler export edges guide fallback, not repository-specific expected symbol lists.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs describe supported stale-id, file-qualified and value-receiver spellings plus preserved ambiguity.
+ * @evidence contracts/performance.md#efficient-algorithms Exact id and symbol probes use generation indexes; a dotted-suffix miss can scan V nodes and collect C matches, while ranking their indexed edge neighborhoods retains the best K in O(CK) time and O(K) additional space for the normal small cap.
+ * @evidence contracts/performance.md#reuse-equivalent-work The graph shares id, symbol and adjacency indexes across handle resolutions; each call ranks a fresh candidate set because the spelling and requested limit can differ.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Candidate lists are request-local and returned to the caller; the resolver retains no history, handle or running task.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation looks handles up in in-memory indexes; a path part of an id is matched as text.
  */
 export function resolveGraphHandle(
   graph: TtscGraphMemory,
@@ -142,15 +150,38 @@ function rank(
   candidateLimit: number,
 ): IResolvedGraphHandle {
   if (resolved.candidates === undefined) return resolved;
-  const ranked = resolved.candidates
-    .map((node) => ({ node, score: candidateScore(graph, node) }))
-    .sort((a, b) => {
-      const score = b.score - a.score;
-      return score !== 0 ? score : compareIdentity(a.node.id, b.node.id);
-    })
-    .slice(0, candidateLimit)
-    .map(({ node }) => node);
-  return { candidates: ranked };
+  const candidates = resolved.candidates;
+  const cap = Math.trunc(candidateLimit);
+  const compare = (
+    a: { node: ITtscGraphNode; score: number },
+    b: { node: ITtscGraphNode; score: number },
+  ): number => {
+    const score = b.score - a.score;
+    return score !== 0 ? score : compareIdentity(a.node.id, b.node.id);
+  };
+  // Large or unusual public caps retain Array.slice semantics; the normal
+  // small cap need not sort every ambiguous declaration in the project.
+  if (!Number.isFinite(cap) || cap < 0 || cap > 32) {
+    return {
+      candidates: candidates
+        .map((node) => ({ node, score: candidateScore(graph, node) }))
+        .sort(compare)
+        .slice(0, candidateLimit)
+        .map(({ node }) => node),
+    };
+  }
+  const ranked: Array<{ node: ITtscGraphNode; score: number }> = [];
+  for (const node of candidates) {
+    const item = { node, score: candidateScore(graph, node) };
+    const position = ranked.findIndex((other) => compare(item, other) < 0);
+    if (position < 0) {
+      if (ranked.length < cap) ranked.push(item);
+    } else if (position < cap) {
+      ranked.splice(position, 0, item);
+      if (ranked.length > cap) ranked.pop();
+    }
+  }
+  return { candidates: ranked.map(({ node }) => node) };
 }
 
 /** Compare position-invariant ids without locale-dependent collation. */

package/src/server/resultAudit.ts

@@ -1,3 +1,31 @@
+import { TTSC_GRAPH_ARTIFACT_NODE_KINDS } from "../structures/TtscGraphArtifactNodeKind";
+
+/**
+ * What the audits say about facts the compiler did not resolve.
+ *
+ * The graph holds two kinds of fact that no compiler pass resolved, and an
+ * audit that called every fact compiler-resolved claimed more than this layer
+ * checked. The memory layer derives structure from compiler-owned declarations:
+ * `file` containers, `contains` ownership, a class member's `property` kind, a
+ * `test` role or `tests` anchor chosen by path convention, and, in a trace,
+ * `dispatches` hops built from `overrides` and `implements`. And an artifact
+ * node is published by a lint plugin that parsed a document, a data model, or
+ * an API description in a process of its own, which is exactly what the dump's
+ * `artifactProducer` records. The text names both, and lists the artifact kinds
+ * from the one vocabulary the memory layer classifies by, so a kind added there
+ * cannot be left out of what the audit disclaims.
+ */
+const NOT_COMPILER_RESOLVED: string = [
+  "The server adds only structure derived from those facts: `file` nodes, `contains` ownership,",
+  "`dispatches` hops, a class member's `property` kind, and the `test` role and `tests` anchors,",
+  "which it assigns from a file's conventional test location rather than from the compiler. A node whose kind is one of",
+  TTSC_GRAPH_ARTIFACT_NODE_KINDS.map((kind) => `\`${kind}\``).join(", ") +
+    " is not",
+  "the compiler's: a lint plugin parsed that artifact in its own process, and the graph returns its",
+  "address, kind, name, and line as that plugin reported them. Nothing else is the server's own,",
+  "so for this snapshot a compiler-resolved fact here cannot disagree with the program.",
+].join("\n");
+
 /**
  * The audit stamped as the first property of every
  * {@link ITtscGraphApplication.IOutput}. Because it serializes before `result`,
@@ -37,25 +65,28 @@
  * layer holds no `Program` and no checker, it runs one pure projection over an
  * in-memory `TtscGraphMemory`, and it selects a constant by request type
  * (#818). What is true is stronger than it sounds and is what the text now
- * says: the compiler resolved these facts when the snapshot was built, the
- * graph holds what it resolved, and this result is a projection of exactly
- * those facts that adds none of its own. A reader who checks that claim finds
- * it holds; a reader who checked the old one found a promise the code could not
- * have kept.
+ * says: the compiler resolved these declaration facts when the snapshot was
+ * built, the graph holds what it resolved, and this result is a projection of
+ * them. The text then names what is not the compiler's, because "adds none of
+ * its own" was itself too strong: the memory layer derives `file` nodes,
+ * `contains` ownership and a member's `property` kind, a trace emits
+ * `dispatches` hops, and an artifact node arrives from a lint plugin's parser.
+ * A reader who checks the claim as now written finds it holds; a reader who
+ * checked the old ones found promises the code could not have kept.
  *
  * ## Two guarantees, not one
  *
  * A returned fact and the set it was chosen from are not audited to the same
  * standard, and one audit that conflated them was dishonest. Every operation
- * resolves each fact it returns — a name, a span, an edge, a signature — to the
- * type-checked program, so a returned fact cannot be wrong for the snapshot.
- * But `lookup`, `entrypoints`, and `tour` do not answer with the structure at a
- * handle you named; they match your natural-language question, score and rank
- * the graph against it, cap hits per file, and cut to a limit. Their `score`
- * and `truncated` fields say so, while the single old audit — "matched, ranked,
- * guessed, or inferred: none" — told the reader the opposite in the same
- * payload, and told it to stop where the shortlist's coverage was exactly what
- * needed judging.
+ * resolves each declaration fact it returns — a name, a span, an edge, a
+ * signature — to the type-checked program, so a returned compiler fact cannot
+ * be wrong for the snapshot. But `lookup`, `entrypoints`, and `tour` do not
+ * answer with the structure at a handle you named; they match your
+ * natural-language question, score and rank the graph against it, cap hits per
+ * file, and cut to a limit. Their `score` and `truncated` fields say so, while
+ * the single old audit — "matched, ranked, guessed, or inferred: none" — told
+ * the reader the opposite in the same payload, and told it to stop where the
+ * shortlist's coverage was exactly what needed judging.
  *
  * So the audits split by what the reader must judge. {@link RESULT_AUDIT} covers
  * the walks from an explicit handle or structure (`trace`, `overview`): the
@@ -79,10 +110,10 @@
 export const RESULT_AUDIT: string = `
 AUDITED BEFORE RETURNING. READ FIRST.
 
-Every fact in this \`result\` — each name, span, edge, signature, and step — was resolved by
-the TypeScript compiler against the program for the snapshot this call synced to, and the
-graph holds what it resolved. This \`result\` is a projection of exactly those facts and adds
-none of its own, so for this snapshot a fact here cannot disagree with the program.
+Every declaration fact in this \`result\` — each name, span, edge, signature, and step — was
+resolved by the TypeScript compiler against the program for the snapshot this call synced to,
+and the graph holds what it resolved. This \`result\` is a projection of those facts.
+${NOT_COMPILER_RESOLVED}
 
 This is the structure the graph holds for the handles you named, not a shortlist matched
 against a natural-language question. Trust every fact it gives and re-verify none: a returned
@@ -102,11 +133,11 @@ after you edit the source.
 export const RESULT_AUDIT_SELECTION: string = `
 AUDITED BEFORE RETURNING. READ FIRST.
 
-Each fact in this \`result\` — every name, span, edge, and signature — was resolved by the
-TypeScript compiler against the program for the snapshot this call synced to, and the graph
-holds what it resolved. This \`result\` is a projection of exactly those facts and adds none of
-its own, so for this snapshot a fact here cannot disagree with the program: a returned span
-is the citation, not a cue to open the file to confirm it.
+Each declaration fact in this \`result\` — every name, span, edge, and signature — was resolved
+by the TypeScript compiler against the program for the snapshot this call synced to, and the
+graph holds what it resolved. This \`result\` is a projection of those facts.
+${NOT_COMPILER_RESOLVED}
+A returned span is the citation, not a cue to open the file to confirm it.
 
 What was selected is heuristic, not exhaustive. This result was matched against your
 natural-language question, scored and ranked, held to a few hits per file, and cut to a
@@ -137,10 +168,10 @@ Follow \`next\` for where that leaves the question.
 export const RESULT_AUDIT_DETAILS: string = `
 AUDITED BEFORE RETURNING. READ FIRST.
 
-Every fact in this \`result\` — each name, span, edge, signature, member, and value — was
-resolved by the TypeScript compiler against the program for the snapshot this call synced to,
-and the graph holds what it resolved. This \`result\` is a projection of exactly those facts
-and adds none of its own, so for this snapshot a fact here cannot disagree with the program.
+Every declaration fact in this \`result\` — each name, span, edge, signature, member, and value —
+was resolved by the TypeScript compiler against the program for the snapshot this call synced
+to, and the graph holds what it resolved. This \`result\` is a projection of those facts.
+${NOT_COMPILER_RESOLVED}
 
 This is the structure the graph holds for the handles you named. What a symbol is — its
 members, its values, its signature — is complete: trust it and do not open the file to read

package/src/server/resultNext.ts

@@ -1,6 +1,17 @@
 import { ITtscGraphNext } from "../structures/ITtscGraphNext";
 
-/** A runner's result structure paired with the next-step calibration for it. */
+/**
+ * A runner's result structure paired with the next-step calibration for it.
+ *
+ * @evidence contracts/common.md#principled-implementation The generic result remains its operation's typed shape while next and optional member truncation qualify how it may be used.
+ * @evidence contracts/common.md#clear-and-simple-design Shared control metadata wraps runner-specific facts without copying all result unions here.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Member caps are explicit so audits cannot silently claim completeness after omission.
+ * @evidence contracts/common.md#meaningful-documentation Native member paragraphs explain next guidance and the capped-member audit consequence.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources data shape only: it holds no handle, task or retained state.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms data shape only: it contains no loop or algorithm.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work data shape only: it computes nothing another request could share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation data shape only: it touches no file, path or process.
+ */
 export interface IRunnerOutput<T> {
   /** The graph result structure. */
   result: T;
@@ -15,6 +26,20 @@ export interface IRunnerOutput<T> {
   membersCapped?: boolean;
 }
 
+/**
+ * Construct a next decision, omitting the request field when none is supplied.
+ *
+ * Callers own the justification for action and any inspect request.
+ *
+ * @evidence contracts/common.md#principled-implementation Typed action/request values retain the supported decision vocabulary and optional-field semantics.
+ * @evidence contracts/common.md#clear-and-simple-design One constructor centralizes omission of absent request metadata without owning runner policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The helper does not infer question intent or add a forced follow-up operation.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states caller policy ownership and conditional field omission.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources returns a plain object and retains nothing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms builds one small object.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work pure constructor, nothing to share.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation builds a plain object; no file, path or process.
+ */
 export function resultNext(
   action: ITtscGraphNext["action"],
   reason: string,