@githolon/dsl 0.50.0 → 0.52.0

package/src/lsp_server.ts

@@ -0,0 +1,404 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * `githolon lsp` — THE AUTHOR-TIME GATE AS A LANGUAGE SERVER (architecture/author_time_gate.md,
+ * slice 3). A thin `vscode-languageserver` (stdio) wrapper over the SAME static-twin machinery
+ * `githolon check` runs: on open/save/change of a `.ts` under a `nomos.package.mjs`'s domain graph,
+ * it composes the package IN-PROCESS (cache-busted TS re-import under tsx — no per-keystroke process
+ * spawn), runs {@link checkDomainModules}, maps findings to source ranges ({@link LawSourceMap}), and
+ * publishes diagnostics (refuse→Error, warn→Warning, note→Information).
+ *
+ * IN-PROCESS, not subprocess: spawning `check_package.mjs` (tsx+node cold start ≈ 150–300 ms) per
+ * keystroke is too slow for red squiggles. The check machinery is pure TS we import directly; the
+ * only cost is re-evaluating changed modules, which the `?t=` cache-bust query forces (proven under
+ * tsx). Composition is memoized per config keyed by the module files' mtimes so an UNCHANGED package
+ * re-checks without re-importing (the cheap warm win).
+ *
+ * Multi-root: each document resolves to its NEAREST `nomos.package.mjs` (walk up), so a repo with
+ * several packages diagnoses each against its own config.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+
+import {
+  createConnection,
+  Diagnostic,
+  DiagnosticSeverity,
+  DidChangeConfigurationNotification,
+  StreamMessageReader,
+  StreamMessageWriter,
+  TextDocuments,
+  TextDocumentSyncKind,
+  type InitializeParams,
+} from "vscode-languageserver/node.js";
+import { TextDocument } from "vscode-languageserver-textdocument";
+
+import { composeDomainModule, type Mod } from "./build_package.js";
+import type { DomainModule } from "./codegen_dart.js";
+import { checkDomainModules, type Finding } from "./law_check.js";
+import { LawSourceMap } from "./law_source_map.js";
+import {
+  currentEvolveLaw,
+  evolveDiff,
+  evolveLawFromDeployJson,
+  evolveLawFromLockfile,
+  type EvolveLaw,
+  type StableIdLockfile,
+} from "./evolve_preview.js";
+
+interface DomainConfig {
+  key: string;
+  name?: string;
+  modules: string[];
+}
+interface PackageConfig {
+  name: string;
+  domains: DomainConfig[];
+}
+
+/** A finding enriched with the resolved source file (absolute) it belongs to. */
+interface LocatedFinding {
+  readonly finding: Finding;
+  readonly file: string;
+  readonly line: number; // 1-based
+  readonly column: number; // 1-based
+}
+
+/** The result of one package check pass. */
+export interface CheckPassResult {
+  /** Findings across the package, each located to a source file. */
+  readonly located: LocatedFinding[];
+  /** A load/compose error (bad config, module that failed to import) — reported on the config file. */
+  readonly error?: string;
+  /** The absolute module file paths in the package (so the caller can clear stale diagnostics). */
+  readonly files: string[];
+  /** The config file path (the anchor for a whole-package load error). */
+  readonly configPath: string;
+}
+
+/** Walk up from `startDir` to find the nearest `nomos.package.mjs`; `undefined` at the filesystem root. */
+export function findNearestConfig(startDir: string): string | undefined {
+  let dir = startDir;
+  for (;;) {
+    const candidate = path.join(dir, "nomos.package.mjs");
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/** A composed package + its provenance, memoized per config keyed by the module files' mtimes. */
+interface ComposedCache {
+  readonly mtimeKey: string;
+  readonly modules: DomainModule[];
+  readonly domainFiles: Map<string, string[]>;
+}
+const composedCache = new Map<string, ComposedCache>();
+
+function mtimeKey(files: readonly string[]): string {
+  return files
+    .map((f) => {
+      try {
+        return `${f}:${statSync(f).mtimeMs}`;
+      } catch {
+        return `${f}:missing`;
+      }
+    })
+    .join("|");
+}
+
+/**
+ * Compose a package's domain modules IN-PROCESS from its config. Cache-busts each `import()` so an
+ * edited module re-evaluates, and memoizes the whole composition by the module files' mtimes so an
+ * unchanged package returns instantly. Throws on a bad config / a module that fails to import.
+ */
+async function composePackage(
+  configPath: string,
+): Promise<{ modules: DomainModule[]; domainFiles: Map<string, string[]> }> {
+  const cfgDir = path.dirname(configPath);
+  const cfgModule = (await import(`${pathToFileURL(configPath).href}?t=${Date.now()}`)) as {
+    default?: PackageConfig;
+  };
+  const cfg = cfgModule.default;
+  if (!cfg || typeof cfg.name !== "string" || !Array.isArray(cfg.domains) || cfg.domains.length === 0) {
+    throw new Error("config must default-export { name, domains: [{ key, modules }, ...] }");
+  }
+
+  // Resolve every module file first so we can compute the mtime cache key before importing.
+  const perDomainFiles: { key: string; name: string | undefined; files: string[] }[] = [];
+  const allFiles: string[] = [];
+  for (const d of cfg.domains) {
+    if (typeof d.key !== "string" || !Array.isArray(d.modules) || d.modules.length === 0) {
+      throw new Error(`each domain needs { key, modules: [path, ...] }; got ${JSON.stringify(d)}`);
+    }
+    const files: string[] = [];
+    for (const rel of d.modules) {
+      const abs = path.resolve(cfgDir, rel);
+      if (!existsSync(abs)) throw new Error(`domain '${d.key}': module not found: ${abs}`);
+      files.push(abs);
+      allFiles.push(abs);
+    }
+    perDomainFiles.push({ key: d.key, name: d.name, files });
+  }
+
+  const key = `${statSync(configPath).mtimeMs}::${mtimeKey(allFiles)}`;
+  const cached = composedCache.get(configPath);
+  if (cached !== undefined && cached.mtimeKey === key) {
+    return { modules: cached.modules, domainFiles: cached.domainFiles };
+  }
+
+  const composed: DomainModule[] = [];
+  const domainFiles = new Map<string, string[]>();
+  for (const d of perDomainFiles) {
+    const mods: Mod[] = [];
+    for (const abs of d.files) {
+      mods.push((await import(`${pathToFileURL(abs).href}?t=${Date.now()}`)) as Mod);
+    }
+    domainFiles.set(d.key, d.files);
+    composed.push(composeDomainModule({ name: d.name ?? d.key, domain: d.key, modules: mods }));
+  }
+  composedCache.set(configPath, { mtimeKey: key, modules: composed, domainFiles });
+  return { modules: composed, domainFiles };
+}
+
+/** Load the `--against` prior evolve law from a deploy.json / build dir / lockfile (LSP variant — throws). */
+function loadPriorEvolveLaw(arg: string, cfgDir: string): EvolveLaw | undefined {
+  const abs = path.isAbsolute(arg) ? arg : path.resolve(cfgDir, arg);
+  if (!existsSync(abs)) return undefined;
+  let file = abs;
+  if (statSync(abs).isDirectory()) {
+    const buildDir = path.join(abs, "build");
+    const scan = (d: string): string | undefined => {
+      if (!existsSync(d)) return undefined;
+      const hit = readdirSync(d).find((f) => f.endsWith(".deploy.json"));
+      return hit !== undefined ? path.join(d, hit) : undefined;
+    };
+    const deploy = scan(abs) ?? scan(buildDir);
+    const lock = path.join(abs, "nomos.stable-ids.json");
+    if (deploy !== undefined) file = deploy;
+    else if (existsSync(lock)) file = lock;
+    else return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+  const p = parsed as Record<string, unknown>;
+  if (p.domains !== undefined && p.interface === undefined && p.packageUsda === undefined) {
+    return evolveLawFromLockfile(parsed as StableIdLockfile);
+  }
+  return evolveLawFromDeployJson(parsed as never);
+}
+
+/** Read the committed `nomos.stable-ids.json` lockfile beside the config (the CURRENT identity). */
+function loadCwdLockfile(cfgDir: string): StableIdLockfile | undefined {
+  const lockPath = path.join(cfgDir, "nomos.stable-ids.json");
+  if (!existsSync(lockPath)) return undefined;
+  try {
+    return JSON.parse(readFileSync(lockPath, "utf8")) as StableIdLockfile;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Run the full author-time check for one package config IN-PROCESS and locate every finding. `against`
+ * (optional, from `nomos.lsp.against`) folds the evolve-preview findings in. Never throws — a load
+ * error is returned as {@link CheckPassResult.error} so the LSP can surface it on the config file.
+ */
+export async function runCheckPass(configPath: string, against?: string): Promise<CheckPassResult> {
+  const cfgDir = path.dirname(configPath);
+  let modules: DomainModule[];
+  let domainFiles: Map<string, string[]>;
+  try {
+    ({ modules, domainFiles } = await composePackage(configPath));
+  } catch (e) {
+    return { located: [], error: (e as Error).message, files: [], configPath };
+  }
+
+  const findings: Finding[] = [...checkDomainModules(modules)];
+
+  if (against !== undefined && against.trim().length > 0) {
+    try {
+      const prior = loadPriorEvolveLaw(against, cfgDir);
+      if (prior !== undefined) {
+        const current = currentEvolveLaw(modules, loadCwdLockfile(cfgDir));
+        findings.push(...evolveDiff(prior, current).findings);
+      }
+    } catch {
+      /* evolve preview is best-effort — never block the base check */
+    }
+  }
+
+  const srcMap = new LawSourceMap(domainFiles);
+  const located: LocatedFinding[] = findings.map((f) => {
+    const loc = srcMap.locate(f.domain, f.directiveId);
+    return {
+      finding: f,
+      file: loc?.file ?? configPath,
+      line: loc?.line ?? 1,
+      column: loc?.column ?? 1,
+    };
+  });
+
+  const files: string[] = [];
+  for (const fs of domainFiles.values()) files.push(...fs);
+  return { located, files, configPath };
+}
+
+/** Map a finding level to an LSP diagnostic severity. */
+function severityOf(level: Finding["level"]): DiagnosticSeverity {
+  return level === "refuse"
+    ? DiagnosticSeverity.Error
+    : level === "warn"
+      ? DiagnosticSeverity.Warning
+      : DiagnosticSeverity.Information;
+}
+
+/** Build the diagnostic for a located finding — a range covering the declaration line's token. */
+function diagnosticFor(lf: LocatedFinding): Diagnostic {
+  const line = Math.max(0, lf.line - 1);
+  const col = Math.max(0, lf.column - 1);
+  return {
+    severity: severityOf(lf.finding.level),
+    range: { start: { line, character: col }, end: { line, character: col + 1 } },
+    source: "githolon",
+    message: `${lf.finding.what} — fix: ${lf.finding.fix}`,
+  };
+}
+
+/** Group located findings by absolute file path into LSP diagnostics. */
+export function groupDiagnostics(located: readonly LocatedFinding[]): Map<string, Diagnostic[]> {
+  const byFile = new Map<string, Diagnostic[]>();
+  for (const lf of located) {
+    const list = byFile.get(lf.file) ?? [];
+    list.push(diagnosticFor(lf));
+    byFile.set(lf.file, list);
+  }
+  return byFile;
+}
+
+/**
+ * Start the language server on stdio. Exported so the launcher (`lsp_main.ts`) and tests can drive it;
+ * the connection is created from `process.stdin`/`process.stdout` by default.
+ */
+export function startServer(): void {
+  // Bind explicitly to stdio (an editor may or may not pass `--stdio`; the streams are unambiguous).
+  const connection = createConnection(
+    new StreamMessageReader(process.stdin),
+    new StreamMessageWriter(process.stdout),
+  );
+  const documents = new TextDocuments(TextDocument);
+
+  let against: string | undefined;
+  // Per config: the set of files we last published diagnostics for (to clear stale ones on re-check).
+  const publishedByConfig = new Map<string, Set<string>>();
+  const debounceTimers = new Map<string, NodeJS.Timeout>();
+
+  connection.onInitialize((params: InitializeParams) => {
+    const init = params.initializationOptions as { against?: string } | undefined;
+    if (init?.against !== undefined) against = init.against;
+    return {
+      capabilities: {
+        textDocumentSync: TextDocumentSyncKind.Incremental,
+      },
+    };
+  });
+
+  connection.onInitialized(() => {
+    void connection.client
+      .register(DidChangeConfigurationNotification.type, undefined)
+      .catch(() => {/* client without config support — the initializationOptions value stands */});
+  });
+
+  connection.onDidChangeConfiguration((change) => {
+    const settings = change.settings as { nomos?: { lsp?: { against?: string } } } | undefined;
+    const next = settings?.nomos?.lsp?.against;
+    if (next !== undefined) {
+      against = next;
+      // Re-check every open TS document under a config.
+      for (const doc of documents.all()) scheduleCheck(doc.uri, 0);
+    }
+  });
+
+  /** Run the check for the config that owns `uri` and publish/clear diagnostics across the package. */
+  async function checkForUri(uri: string): Promise<void> {
+    let fsPath: string;
+    try {
+      fsPath = fileURLToPath(uri);
+    } catch {
+      return;
+    }
+    if (!fsPath.endsWith(".ts")) return;
+    const configPath = findNearestConfig(path.dirname(fsPath));
+    if (configPath === undefined) return;
+
+    const result = await runCheckPass(configPath, against);
+
+    if (result.error !== undefined) {
+      // A whole-package load error → one diagnostic on the config file.
+      connection.sendDiagnostics({
+        uri: pathToFileURL(configPath).href,
+        diagnostics: [
+          {
+            severity: DiagnosticSeverity.Error,
+            range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } },
+            source: "githolon",
+            message: `githolon check could not load the package: ${result.error}`,
+          },
+        ],
+      });
+      return;
+    }
+    // Clear any prior config-file load error.
+    connection.sendDiagnostics({ uri: pathToFileURL(configPath).href, diagnostics: [] });
+
+    const byFile = groupDiagnostics(result.located);
+    const nowPublished = new Set<string>();
+    for (const [file, diags] of byFile) {
+      connection.sendDiagnostics({ uri: pathToFileURL(file).href, diagnostics: diags });
+      nowPublished.add(file);
+    }
+    // Clear diagnostics for files that had findings last time but are now clean.
+    const prev = publishedByConfig.get(configPath) ?? new Set<string>();
+    for (const file of prev) {
+      if (!nowPublished.has(file)) {
+        connection.sendDiagnostics({ uri: pathToFileURL(file).href, diagnostics: [] });
+      }
+    }
+    // Also make sure every module file with NO findings is cleared (fresh-open case).
+    for (const file of result.files) {
+      if (!nowPublished.has(file)) {
+        connection.sendDiagnostics({ uri: pathToFileURL(file).href, diagnostics: [] });
+      }
+    }
+    publishedByConfig.set(configPath, nowPublished);
+  }
+
+  function scheduleCheck(uri: string, delayMs: number): void {
+    const existing = debounceTimers.get(uri);
+    if (existing !== undefined) clearTimeout(existing);
+    debounceTimers.set(
+      uri,
+      setTimeout(() => {
+        debounceTimers.delete(uri);
+        void checkForUri(uri).catch((e) => connection.console.error(`githolon lsp: ${String(e)}`));
+      }, delayMs),
+    );
+  }
+
+  // Open + save are immediate; change is debounced (~500 ms) so we don't re-check every keystroke.
+  documents.onDidOpen((e) => scheduleCheck(e.document.uri, 0));
+  documents.onDidSave((e) => scheduleCheck(e.document.uri, 0));
+  documents.onDidChangeContent((e) => scheduleCheck(e.document.uri, 500));
+
+  documents.listen(connection);
+  connection.listen();
+}