semantic-js-mcp 0.10.2 → 0.10.4

package/scripts/smoke.mjs

@@ -9,6 +9,7 @@ import {Client} from "@modelcontextprotocol/sdk/client/index.js";
 import {StdioClientTransport} from "@modelcontextprotocol/sdk/client/stdio.js";
 import {parse as parseYaml} from "yaml";
 import {fileIdentity, locationKey, locationKeyAt, locationKeyForOperatingSystem} from "../lib/file-identity.mjs";
+import {diagnosticUseSummary} from "../lib/diagnostic-evidence.mjs";
 import {removeTemporaryDirectory} from "../lib/temporary-directory.mjs";
 import {
   ACCOUNTING_STATUS,
@@ -22,6 +23,7 @@ import {
   DIAGNOSTIC_REGION,
   EVIDENCE_STATUS,
   DIAGNOSTIC_FRESHNESS,
+  DIAGNOSTIC_GUIDANCE,
   ENVIRONMENT_VARIABLE,
   ERROR_CODE,
   FINGERPRINT_FORMAT,
@@ -49,6 +51,35 @@ function assert(condition, message) {
   if (!condition) throw new Error(message);
 }
 
+const unversionedDiagnosticUse = diagnosticUseSummary({versionConfirmed: false, reportReceived: true});
+deepStrictEqual(
+  unversionedDiagnosticUse,
+  {
+    currentDocumentDiagnosticsAvailable: false,
+    unconfirmedDiagnosticReportAvailable: true,
+    usableAsCurrentDocumentDiagnosticEvidence: false,
+    guidance: DIAGNOSTIC_GUIDANCE.UNCONFIRMED_DIAGNOSTIC_REPORT_AVAILABLE,
+  },
+  "Unversioned diagnostic reports did not remain context-only",
+);
+const unavailableDiagnosticUse = diagnosticUseSummary({versionConfirmed: false, reportReceived: false});
+deepStrictEqual(
+  unavailableDiagnosticUse,
+  {
+    currentDocumentDiagnosticsAvailable: false,
+    unconfirmedDiagnosticReportAvailable: false,
+    usableAsCurrentDocumentDiagnosticEvidence: false,
+    guidance: DIAGNOSTIC_GUIDANCE.CURRENT_DOCUMENT_DIAGNOSTICS_UNAVAILABLE,
+  },
+  "Missing current-document reports did not remain unavailable as validation",
+);
+
+function assertDiagnosticUse(result, message) {
+  const versionConfirmed = result.evidence.status === EVIDENCE_STATUS.VERIFIED;
+  const reportReceived = versionConfirmed || result.unconfirmedDiagnosticReport?.reportReceived === true;
+  deepStrictEqual(result.diagnosticUse, diagnosticUseSummary({versionConfirmed, reportReceived}), message);
+}
+
 const windowsLocation = {
   file: "C:\\Repository\\src\\Example.ts",
   range: {start: {line: 2, column: 17}},
@@ -396,6 +427,7 @@ try {
     "Concurrent diagnostics disagreed about snapshot evidence",
   );
   const initialDiagnosticsVerified = initialDiagnostics.result.evidence.status === EVIDENCE_STATUS.VERIFIED;
+  assertDiagnosticUse(initialDiagnostics.result, "Initial diagnostics returned inconsistent usage guidance");
   assert(
     initialDiagnostics.collection.status === (initialDiagnosticsVerified ? COLLECTION_STATUS.COMPLETE : COLLECTION_STATUS.PARTIAL),
     "Diagnostics evidence status and collection status disagree",
@@ -411,6 +443,18 @@ try {
   );
   if (!initialDiagnosticsVerified) {
     assert(initialDiagnostics.result.unconfirmedDiagnosticReport, "Untrusted diagnostics omitted their separated report");
+    if (initialDiagnostics.result.evidence.reason === DIAGNOSTIC_EVIDENCE_REASON.LANGUAGE_SERVER_VERSION_NOT_REPORTED) {
+      assert(
+        initialDiagnostics.result.diagnosticUse.unconfirmedDiagnosticReportAvailable === true,
+        "Unversioned diagnostics did not expose their unconfirmed report",
+      );
+    }
+    if (initialDiagnostics.result.evidence.reason === DIAGNOSTIC_EVIDENCE_REASON.LANGUAGE_SERVER_DID_NOT_REPORT_CURRENT_DOCUMENT) {
+      assert(
+        initialDiagnostics.result.diagnosticUse.unconfirmedDiagnosticReportAvailable === false,
+        "Missing diagnostics claimed that an unconfirmed report was available",
+      );
+    }
   }
 
   const textCount = assertResult(
@@ -850,6 +894,7 @@ try {
     ].join("\n"),
   );
   const supersededDiagnostics = assertResult(await supersededDiagnosticsPromise, TOOL.DIAGNOSTICS);
+  assertDiagnosticUse(supersededDiagnostics.result, "Superseded diagnostics returned inconsistent usage guidance");
   assert(
     supersededDiagnostics.result.evidence.status === EVIDENCE_STATUS.UNTRUSTED,
     "Diagnostics trusted content that changed during acquisition",
@@ -864,6 +909,7 @@ try {
   ]);
   const changedDiagnostics = assertResult(changedDiagnosticsResponse, TOOL.DIAGNOSTICS);
   const concurrentChangedDiagnostics = assertResult(concurrentChangedDiagnosticsResponse, TOOL.DIAGNOSTICS);
+  assertDiagnosticUse(changedDiagnostics.result, "Changed diagnostics returned inconsistent usage guidance");
   deepStrictEqual(
     concurrentChangedDiagnostics.result.document,
     changedDiagnostics.result.document,
@@ -930,6 +976,7 @@ try {
         declarationExclusionAccounting: "ok",
         nodeModuleExtensions: "ok",
         diagnosticVersionReporting: "ok",
+        actionableDiagnosticUse: "ok",
         sharedDiagnosticAcquisition: "ok",
         diagnosticContentFreshness: "ok",
         diagnosticProvenance: "ok",

package/scripts/vue-smoke.mjs

@@ -15,6 +15,7 @@ import {
   DEFINITION_RESOLUTION_METHOD,
   DEFINITION_SELECTION_STATUS,
   DIAGNOSTIC_EVIDENCE_REASON,
+  DIAGNOSTIC_GUIDANCE,
   DIAGNOSTIC_LANGUAGE,
   DIAGNOSTIC_PROVIDER,
   DIAGNOSTIC_REGION,
@@ -159,6 +160,16 @@ try {
   ) {
     throw new Error("Vue diagnostic pull omitted its snapshot-confirmation reason");
   }
+  deepStrictEqual(
+    vueDiagnosticsResponse.structuredContent?.result?.diagnosticUse,
+    {
+      currentDocumentDiagnosticsAvailable: true,
+      unconfirmedDiagnosticReportAvailable: false,
+      usableAsCurrentDocumentDiagnosticEvidence: true,
+      guidance: DIAGNOSTIC_GUIDANCE.CURRENT_DOCUMENT_DIAGNOSTICS_AVAILABLE,
+    },
+    "Vue diagnostic pull returned inconsistent usage guidance",
+  );
   const provenanceDiagnostics = await client.callTool({
     name: TOOL.DIAGNOSTICS,
     arguments: {file: diagnosticComponent, root: workspace},

package/server.mjs

@@ -12,6 +12,7 @@ import * as z from "zod/v4";
 import {stringify as stringifyYaml} from "yaml";
 import {PACKAGE_ROOT, inspectRuntimeComponents, resolveRuntimeComponent, runtimeDependencyRoot} from "./lib/runtime.mjs";
 import {fileIdentity, locationKey, locationKeyAt} from "./lib/file-identity.mjs";
+import {diagnosticUseSummary} from "./lib/diagnostic-evidence.mjs";
 import {isNamedSymbolTool, namedSemanticEvidence, namedSemanticEvidenceMatches} from "./lib/semantic-evidence.mjs";
 import {PendingRequestRegistry} from "./lib/pending-requests.mjs";
 import {collectStableSnapshot} from "./lib/stable-collection.mjs";
@@ -29,6 +30,7 @@ import {
   DIAGNOSTIC_LANGUAGE,
   DIAGNOSTIC_PROVIDER,
   DIAGNOSTIC_REGION,
+  DIAGNOSTIC_RESULT_FIELD,
   DIAGNOSTIC_SEVERITY,
   EVIDENCE_STATUS,
   ENVIRONMENT_VARIABLE,
@@ -2682,6 +2684,7 @@ server.registerTool(
       return toolResult(tool, {
         request: {file: context.file, searchScope: SEARCH_SCOPE.DOCUMENT, resultLimit: normalizedLimit(maxResults)},
         result: {
+          [DIAGNOSTIC_RESULT_FIELD.DIAGNOSTIC_USE]: diagnosticUseSummary({versionConfirmed, reportReceived: report.reportReceived}),
           provenance: {provider: provenance.provider, documentLanguage: provenance.documentLanguage},
           evidence: {
             status: versionConfirmed ? EVIDENCE_STATUS.VERIFIED : EVIDENCE_STATUS.UNTRUSTED,
@@ -2691,10 +2694,11 @@ server.registerTool(
             version: report.documentVersion,
             contentFingerprint: publicContentFingerprint(report.documentContentFingerprint),
           },
-          diagnosticsForCurrentDocument: versionConfirmed ? diagnosticReport : null,
-          unconfirmedDiagnosticReport: versionConfirmed
+          [DIAGNOSTIC_RESULT_FIELD.DIAGNOSTICS_FOR_CURRENT_DOCUMENT]: versionConfirmed ? diagnosticReport : null,
+          [DIAGNOSTIC_RESULT_FIELD.UNCONFIRMED_DIAGNOSTIC_REPORT]: versionConfirmed
             ? undefined
             : {
+                [DIAGNOSTIC_RESULT_FIELD.REPORT_RECEIVED]: report.reportReceived,
                 ...diagnosticReport,
                 languageServerReportedDocumentVersion: report.reportedDocumentVersion,
                 freshness: report.freshness,

package/skills/semantic-navigation/SKILL.md

@@ -101,7 +101,9 @@ Use the reported `referenceSetId` with `lsp_unresolved_reference_page` when unre
 
 Reference collections include `collection.contentFreshness: verified-current-file-content` and `collection.repositoryInventoryFreshness: verified-current-repository-source-inventory`. `lsp_reference_page` verifies direct content hashes plus the repository source inventory before returning a page. This detects new, deleted, renamed, and normally modified source files. A change returns `error.code: REFERENCE_SET_CONTENT_CHANGED`; an expired or evicted set returns `REFERENCE_SET_NOT_FOUND_OR_EXPIRED`. Call `lsp_references` to create a current set. `REPOSITORY_CHANGED_DURING_COLLECTION` means edits did not settle during the collection attempts.
 
-Diagnostics identify the analyzed document with a version and SHA-256 fingerprint. Treat only `result.evidence.status: verified` and a non-null `diagnosticsForCurrentDocument` as current diagnostic evidence. `evidence.status: untrusted` places any report under `unconfirmedDiagnosticReport`, keeps `diagnosticsForCurrentDocument` null, and produces `collection.status: partial`. Do not interpret an empty unconfirmed report as a clean file.
+Diagnostics identify the analyzed document with a version and SHA-256 fingerprint. Read `result.diagnosticUse` before reading diagnostic items. Only `currentDocumentDiagnosticsAvailable: true` and `usableAsCurrentDocumentDiagnosticEvidence: true` permit using `diagnosticsForCurrentDocument` as current diagnostic evidence. This evidence is still not proof of correctness; run applicable repository-native checks before making that claim.
+
+`evidence.status: untrusted` keeps `diagnosticsForCurrentDocument` null and produces `collection.status: partial`. `unconfirmedDiagnosticReportAvailable: true` means the provider emitted a report that is available only as context under `unconfirmedDiagnosticReport`; it is not current-document, compile, or type validation. `false` means no unconfirmed provider report was available. In both cases, follow `diagnosticUse.guidance` and do not interpret missing or empty unconfirmed items as a clean file.
 
 `current-document-version-confirmed` means a push report carried the current document version. `current-document-snapshot-confirmed` means a provider-supported pull completed while the synchronized and filesystem content remained unchanged. `document-content-changed-during-diagnostic-acquisition` is untrusted evidence and requires a new diagnostic call after the file settles.
 

package/skills/semantic-navigation/references/protocol-literals.md

@@ -2,7 +2,7 @@
 
 Generated from `protocol.mjs`. Do not edit this file directly.
 
-Producer: `semantic-js-mcp` version `0.10.2`
+Producer: `semantic-js-mcp` version `0.10.4`
 Display name: `Semantic JS MCP`
 Result schema version: `7`
 
@@ -40,7 +40,7 @@ Result schema version: `7`
 - `lsp_workspace_symbols`: `Returns declaration-shaped symbols whose names contain a query. Use lsp_count_named_symbol or lsp_audit_named_symbol with an exact name.`
 - `lsp_definition`: `Resolves definitions for one source position. Use lsp_hover for type information or lsp_count_references for impact scope.`
 - `lsp_hover`: `Returns inferred type information and documentation for one source position. Use lsp_definition for declaration identity.`
-- `lsp_diagnostics`: `Returns diagnostics for one file and marks evidence untrusted when the current document snapshot cannot be confirmed.`
+- `lsp_diagnostics`: `Returns diagnostics for one file, separates unconfirmed context, and states whether the result is usable as current-document diagnostic evidence.`
 - `lsp_count_text_matches`: `Counts exact identifier text matches without semantic verification. Use lsp_count_named_symbol or lsp_audit_named_symbol to verify identity.`
 - `lsp_count_named_symbol`: `Returns exact-definition and verified-reference counts plus explicit semantic follow-up status for a symbol name. Use lsp_audit_named_symbol for identity, signature, or file-hint binding verification and lsp_reference_page with a returned referenceSetId for locations.`
 - `lsp_count_references`: `Returns verified-reference counts for the symbol at one source position. Use lsp_audit_symbol for identity and signature or lsp_reference_page with the returned referenceSetId for locations.`
@@ -236,6 +236,23 @@ Result schema version: `7`
 - `language-server-reported-different-version`
 - `language-server-did-not-report-current-document`
 
+## Diagnostic Result Fields
+
+- `diagnosticUse`
+- `diagnosticsForCurrentDocument`
+- `unconfirmedDiagnosticReport`
+- `reportReceived`
+- `currentDocumentDiagnosticsAvailable`
+- `unconfirmedDiagnosticReportAvailable`
+- `usableAsCurrentDocumentDiagnosticEvidence`
+- `guidance`
+
+## Diagnostic Guidance
+
+- `Use these as current-document diagnostic evidence, not proof of correctness. Run applicable repository-native checks before claiming correctness.`
+- `Treat the unconfirmed report as context only. It is not current-document, compile, or type validation. Run applicable repository-native typecheck, compile, or focused test commands.`
+- `Current-document diagnostics are unavailable. Do not interpret this as a clean file. Run applicable repository-native typecheck, compile, or focused test commands.`
+
 ## Evidence Status
 
 - `verified`

package/AGENT_SETUP.md

@@ -1,176 +0,0 @@
-# Agent Setup
-
-This guide is for a coding agent whose user has explicitly requested that it
-install, configure, update, verify, roll back, or remove Semantic JS MCP. It is
-not an instruction to change an environment merely because this file was read.
-
-## Scope
-
-First identify the application that will run the MCP server. That application
-is the MCP host. Use the verified Codex procedure only for Codex. For every
-other host, use the generic stdio procedure below and translate its fields into
-the host's documented configuration format. Do not guess a configuration file
-or schema.
-
-Semantic JS MCP requires Node.js 22 or newer and `rg` (ripgrep) on `PATH`.
-Before changing host configuration, run:
-
-```bash
-node --version
-rg --version
-```
-
-Stop if Node.js is older than 22 or either command is unavailable. Report the
-missing prerequisite. Do not continue with a partial installation.
-
-## Safety Boundaries
-
-This guide does not override system, developer, organization, repository, or
-host security policy.
-
-- Inspect existing configuration before editing it and change only the entry
-  approved by the user.
-- Request any approval required for package installation, global writes,
-  configuration changes, network access, or process restart.
-- Never request or expose credentials, disable security controls, or execute a
-  remote shell pipeline.
-- Preserve every unrelated MCP server and setting. Never replace an entire
-  configuration file to add one server.
-- Stop and report the blocker when the requested host or prerequisite cannot be
-  verified safely.
-
-## Installation Procedure
-
-### Codex
-
-Use the public marketplace adapter:
-
-```bash
-codex plugin marketplace add elnonathan/semantic-js-mcp
-codex plugin add semantic-js-mcp@elnonathan
-codex plugin list
-```
-
-Start a new Codex session after installation. The plugin supplies both the MCP
-server and the semantic-navigation skill.
-
-### Generic Stdio Hosts
-
-Use this procedure only when the host supports local MCP servers over stdio. If
-that capability cannot be confirmed from installed help or host documentation,
-stop and report that the host is unsupported or unverified.
-
-After the user approves the package installation and configuration change,
-install the executable:
-
-```bash
-npm install --global semantic-js-mcp
-```
-
-Inspect the existing host configuration. Add exactly one MCP server with these
-values:
-
-- server name: `semanticjsmcp`
-- transport: `stdio`
-- executable or command: `semantic-js-mcp`
-- arguments: one argument, `serve`
-- enabled: `true`, when the host has an enabled field
-
-Do not configure a URL, port, shell command, or credentials. The host must
-start `semantic-js-mcp serve` as a local child process and communicate through
-standard input and standard output. Translate the values above into the host's
-documented schema; do not copy a configuration shape from a different host.
-
-Save the smallest possible change. Restart or reload the host when its
-documentation requires it.
-
-## Verification
-
-For an executable installation, record the installed version and run the
-doctor:
-
-```bash
-semantic-js-mcp --version
-semantic-js-mcp doctor
-```
-
-Read the structured doctor result literally:
-
-- `pass`: continue to host tool verification.
-- `untrusted`: continue to host tool verification and report the stated
-  uncertainty. Do not describe it as `pass`.
-- `blocked` or `fail`: stop, correct the reported problem when authorized, or
-  report the blocker. Do not claim a successful installation.
-
-Then verify the host discovers tools whose base names begin with `lsp_`. A host
-may display the server name before the base name. Execute one read-only call
-such as `lsp_document_symbols` against a user-approved JavaScript, TypeScript,
-or Vue file. Do not claim successful installation from configuration text
-alone.
-
-For a Codex plugin installation without a global executable, verify the version
-with `codex plugin list`, start a new session, and confirm MCP tool discovery
-there.
-
-Installation is successful only when the host discovers the MCP tools and one
-read-only `lsp_*` call returns a result. Package installation or configuration
-text alone is not success.
-
-## Update And Rollback
-
-Update an existing Codex installation by refreshing its marketplace snapshot
-before reinstalling:
-
-```bash
-codex plugin marketplace upgrade elnonathan
-codex plugin add semantic-js-mcp@elnonathan
-codex plugin list
-```
-
-Update a global npm installation with:
-
-```bash
-npm install --global semantic-js-mcp@latest
-```
-
-Before updating, record the working version. To roll back a global installation,
-install that exact known version, for example:
-
-```bash
-npm install --global semantic-js-mcp@0.10.1
-```
-
-For a host adapter, restore the previously recorded package version and host
-configuration together. Do not replace or remove unrelated configuration while
-rolling back.
-
-## Removal
-
-For Codex, remove only this plugin:
-
-```bash
-codex plugin remove semantic-js-mcp@elnonathan
-```
-
-Remove the `elnonathan` marketplace only when the user confirms that no other
-installed plugin uses it:
-
-```bash
-codex plugin marketplace remove elnonathan
-```
-
-For a global executable, remove the package and only its `semanticjsmcp` MCP
-entry:
-
-```bash
-npm uninstall --global semantic-js-mcp
-```
-
-Restart the host and confirm the tools are no longer registered.
-
-## Completion Report
-
-Report the detected host, installed or removed version, exact configuration
-entry changed, doctor status when available, tool-discovery result, required
-restart, and any remaining uncertainty. Do not include credentials or unrelated
-configuration values.