@mrclrchtr/supi-code-intelligence 3.2.0 → 4.1.0

package/src/analysis/architecture/model.ts

@@ -1,76 +1,143 @@
-/**
- * Architecture model types and query helpers.
- *
- * Discovery logic lives in {@link ./discovery.ts}.
- */
+/** Direct manifest and workspace-configuration facts for Orientation and the session overview. */
 
 import * as path from "node:path";
 import { isWithinOrEqual } from "@mrclrchtr/supi-core/project";
 
-// ── Types ─────────────────────────────────────────────────────────────
+/** Completion state for one directly observed architecture collection. */
+export type ArchitectureObservationStatus = "complete" | "partial" | "unavailable";
 
-export interface ArchitectureModel {
-  /** Absolute root directory of the project */
-  root: string;
-  /** Project name from root manifest */
-  name: string | null;
-  /** Project description from root manifest */
-  description: string | null;
-  /** Detected modules/packages */
-  modules: ModuleInfo[];
-  /** Internal dependency edges between modules */
-  edges: DependencyEdge[];
+/** Manifest fields whose values are surfaced without assigning a derived role. */
+export interface ManifestField {
+  /** Exact field path in the package manifest, such as `exports` or `pi.extensions`. */
+  readonly field: string;
+  /** JSON value declared at that field. */
+  readonly value: unknown;
+}
+
+/** One dependency declaration from an exact package-manifest section. */
+export interface ManifestDependency {
+  /** Source package.json field. */
+  readonly field: ManifestDependencyField;
+  /** Dependency name as declared in the manifest object key. */
+  readonly name: string;
+  /** Version/range value as declared in the manifest object value. */
+  readonly specifier: unknown;
 }
 
+/** Dependency-map fields whose entries may declare package relationships. */
+export type ManifestDependencyField =
+  | "dependencies"
+  | "devDependencies"
+  | "optionalDependencies"
+  | "peerDependencies";
+
+/** One dependency-map field retained with its source field name. */
+export interface ManifestDependencySection {
+  /** Source package.json field. */
+  readonly field: ManifestDependencyField;
+  /** Every directly declared dependency entry in the section. */
+  readonly entries: readonly ManifestDependency[];
+}
+
+/** Facts from one successfully parsed package.json file. */
 export interface ModuleInfo {
-  /** Package/module name */
-  name: string;
-  /** Short description from manifest */
-  description: string | null;
-  /** Absolute path to the module root */
-  root: string;
-  /** Relative path from project root */
-  relativePath: string;
-  /** Main entrypoint(s) from manifest */
-  entrypoints: string[];
-  /** Whether this is a leaf module (no internal dependents) */
-  isLeaf: boolean;
-  /** Internal dependency names */
-  internalDeps: string[];
-  /** External dependency names */
-  externalDeps: string[];
+  /** Package name from package.json; null when the manifest omits a string name. */
+  readonly name: string | null;
+  /** Package description from package.json when it is a string. */
+  readonly description: string | null;
+  /** Absolute package directory. */
+  readonly root: string;
+  /** Package directory relative to the orientation root. */
+  readonly relativePath: string;
+  /** Package manifest path relative to the orientation root. */
+  readonly manifestPath: string;
+  /** Directly declared non-dependency manifest fields. */
+  readonly fields: readonly ManifestField[];
+  /** Directly declared dependency-map sections. */
+  readonly dependencySections: readonly ManifestDependencySection[];
+}
+
+/** Result of reading the root package manifest. */
+export interface PackageManifestObservation {
+  /** Whether the root package manifest was read and parsed. */
+  readonly status: ArchitectureObservationStatus;
+  /** Root-relative path of the expected manifest. */
+  readonly path: string;
+  /** Failure explanation when the manifest is partial or unavailable. */
+  readonly reason: string | null;
+  /** Parsed package facts when available. */
+  readonly package: ModuleInfo | null;
+}
+
+/** Configuration file and field that declared workspace membership. */
+export interface WorkspaceTopologySource {
+  /** Root-relative configuration file path. */
+  readonly path: string;
+  /** Exact configuration field. */
+  readonly field: string;
+}
+
+/** Directly observed package-topology collection state. */
+export interface WorkspaceTopology {
+  /** Whether this is a workspace declaration, one root package, or unavailable metadata. */
+  readonly kind: "workspace" | "single-package" | "unavailable";
+  /** Collection completion state. */
+  readonly status: ArchitectureObservationStatus;
+  /** Configuration source that declared workspace membership, when applicable. */
+  readonly source: WorkspaceTopologySource | null;
+  /** Failure explanation when discovery was partial or unavailable. */
+  readonly reason: string | null;
+  /** Package manifests matched by configuration but not successfully parsed. */
+  readonly failedPackageManifestCount: number;
 }
 
+/** One manifest-declared dependency whose name matches exactly one discovered package. */
 export interface DependencyEdge {
-  /** Source module name */
-  from: string;
-  /** Target module name */
-  to: string;
+  /** Declaring package name. */
+  readonly from: string;
+  /** Declared package name that identifies one discovered package. */
+  readonly to: string;
+  /** Exact dependency-map field that declared the relationship. */
+  readonly field: ManifestDependencyField;
+  /** Declared version/range value. */
+  readonly specifier: unknown;
+  /** Root-relative manifest that declared the relationship. */
+  readonly manifestPath: string;
 }
 
-// ── Query helpers ─────────────────────────────────────────────────────
+/**
+ * Factual package and workspace observations.
+ *
+ * `modules` and `edges` describe manifest declarations only; they are not a
+ * runtime architecture graph.
+ */
+export interface ArchitectureModel {
+  /** Absolute supported workspace root, or the requested cwd when no supported metadata exists. */
+  readonly root: string;
+  /** Root package manifest observation. */
+  readonly rootManifest: PackageManifestObservation;
+  /** Workspace membership observation. */
+  readonly topology: WorkspaceTopology;
+  /** Parsed package manifests declared by the selected topology. */
+  readonly modules: readonly ModuleInfo[];
+  /** Manifest-declared dependencies between uniquely discovered packages. */
+  readonly edges: readonly DependencyEdge[];
+  /** Root package name when directly declared. */
+  readonly name: string | null;
+  /** Root package description when directly declared. */
+  readonly description: string | null;
+}
 
+/** Find the most specific discovered package containing a filesystem path. */
 export function findModuleForPath(model: ArchitectureModel, filePath: string): ModuleInfo | null {
   const resolved = path.resolve(filePath);
   let best: ModuleInfo | null = null;
 
   for (const mod of model.modules) {
-    if (isWithinOrEqual(mod.root, resolved)) {
-      if (!best || mod.root.length > best.root.length) {
-        best = mod;
-      }
+    if (isWithinOrEqual(mod.root, resolved) && (!best || mod.root.length > best.root.length)) {
+      best = mod;
     }
   }
 
   return best;
 }
-
-export function getDependents(model: ArchitectureModel, moduleName: string): ModuleInfo[] {
-  return model.modules.filter((m) => m.internalDeps.includes(moduleName));
-}
-
-export function getDependencies(model: ArchitectureModel, moduleName: string): ModuleInfo[] {
-  const mod = model.modules.find((m) => m.name === moduleName);
-  if (!mod) return [];
-  return model.modules.filter((m) => mod.internalDeps.includes(m.name));
-}

package/src/analysis/architecture/workspace-config.ts

@@ -0,0 +1,229 @@
+/** Supported workspace-configuration parsing and pattern validation. */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseDocument } from "yaml";
+import { errorMessage, isRecord, type PackageJsonRead, readPackageJson } from "./manifest.ts";
+import type { WorkspaceTopologySource } from "./model.ts";
+
+export const PNPM_WORKSPACE = "pnpm-workspace.yaml";
+
+/** Parsed supported workspace membership declaration. */
+export type WorkspaceDeclaration =
+  | {
+      readonly kind: "workspace";
+      readonly source: WorkspaceTopologySource;
+      readonly patterns: string[];
+    }
+  | { readonly kind: "single-package" }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+type PatternValidation =
+  | { readonly kind: "complete"; readonly patterns: string[] }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+type ParsedPattern =
+  | {
+      readonly kind: "complete";
+      readonly pattern: { readonly value: string; readonly negative: boolean };
+    }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+/** Prefer an enclosing workspace declaration, then the nearest package manifest. */
+export function findArchitectureRoot(cwd: string): string {
+  const directories = ancestors(path.resolve(cwd));
+  const pnpmRoot = directories.find((directory) =>
+    fs.existsSync(path.join(directory, PNPM_WORKSPACE)),
+  );
+  if (pnpmRoot) return pnpmRoot;
+
+  const packageWorkspaceRoot = directories.find((directory) => {
+    const manifest = readPackageJson(directory);
+    return manifest.kind === "complete" && Object.hasOwn(manifest.value, "workspaces");
+  });
+  if (packageWorkspaceRoot) return packageWorkspaceRoot;
+
+  return (
+    directories.find((directory) => fs.existsSync(path.join(directory, "package.json"))) ?? cwd
+  );
+}
+
+/** Read only the supported package.json/pnpm workspace membership declarations. */
+export function readWorkspaceDeclaration(
+  root: string,
+  rootRead: PackageJsonRead,
+): WorkspaceDeclaration {
+  const pnpmPath = path.join(root, PNPM_WORKSPACE);
+  if (fs.existsSync(pnpmPath)) return readPnpmWorkspaceDeclaration(pnpmPath);
+
+  if (rootRead.kind !== "complete") {
+    return {
+      kind: "unavailable",
+      reason:
+        "No supported workspace configuration is available because the root package manifest could not be read.",
+    };
+  }
+
+  if (!Object.hasOwn(rootRead.value, "workspaces")) return { kind: "single-package" };
+  const workspaces = rootRead.value.workspaces;
+  const patterns = Array.isArray(workspaces)
+    ? workspaces
+    : isRecord(workspaces) && Array.isArray(workspaces.packages)
+      ? workspaces.packages
+      : null;
+  if (!patterns) {
+    return {
+      kind: "unavailable",
+      reason:
+        "package.json#workspaces must be a string array or an object with a string packages array.",
+    };
+  }
+
+  const validated = validateWorkspacePatterns(patterns);
+  if (validated.kind === "unavailable") return validated;
+  if (validated.patterns.length === 0) return { kind: "single-package" };
+  return {
+    kind: "workspace",
+    source: {
+      path: "package.json",
+      field: Array.isArray(workspaces) ? "workspaces" : "workspaces.packages",
+    },
+    patterns: validated.patterns,
+  };
+}
+
+function readPnpmWorkspaceDeclaration(workspacePath: string): WorkspaceDeclaration {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(workspacePath, "utf-8");
+  } catch (error) {
+    return {
+      kind: "unavailable",
+      reason: `Could not read ${PNPM_WORKSPACE}: ${errorMessage(error)}`,
+    };
+  }
+
+  let value: unknown;
+  try {
+    const document = parseDocument(raw);
+    if (document.errors.length > 0) {
+      return {
+        kind: "unavailable",
+        reason: `Could not parse ${PNPM_WORKSPACE}: ${document.errors[0]?.message ?? "invalid YAML"}`,
+      };
+    }
+    value = document.toJS();
+  } catch (error) {
+    return {
+      kind: "unavailable",
+      reason: `Could not parse ${PNPM_WORKSPACE}: ${errorMessage(error)}`,
+    };
+  }
+
+  if (!isRecord(value)) {
+    return { kind: "unavailable", reason: `${PNPM_WORKSPACE} must contain a YAML mapping.` };
+  }
+  if (!Object.hasOwn(value, "packages")) return { kind: "single-package" };
+  if (!Array.isArray(value.packages)) {
+    return { kind: "unavailable", reason: `${PNPM_WORKSPACE}#packages must be a string array.` };
+  }
+
+  const validated = validateWorkspacePatterns(value.packages);
+  if (validated.kind === "unavailable") return validated;
+  if (validated.patterns.length === 0) return { kind: "single-package" };
+  return {
+    kind: "workspace",
+    source: { path: PNPM_WORKSPACE, field: "packages" },
+    patterns: validated.patterns,
+  };
+}
+
+function validateWorkspacePatterns(values: unknown[]): PatternValidation {
+  const parsed = values.map(parseWorkspacePattern);
+  const invalid = parsed.find(
+    (entry): entry is Extract<PatternValidation, { kind: "unavailable" }> =>
+      entry.kind === "unavailable",
+  );
+  if (invalid) return invalid;
+
+  const patterns = parsed
+    .filter(
+      (entry): entry is Extract<ParsedPattern, { kind: "complete" }> => entry.kind === "complete",
+    )
+    .map((entry) => entry.pattern);
+  if (patterns.length > 0 && patterns.every((pattern) => pattern.negative)) {
+    return {
+      kind: "unavailable",
+      reason:
+        "Workspace configuration contains only exclusion patterns and cannot establish package membership.",
+    };
+  }
+  if (reincludesAfterExclusion(patterns)) {
+    return {
+      kind: "unavailable",
+      reason:
+        "Workspace patterns that re-include a path after an exclusion are unsupported; module discovery is unavailable rather than approximated.",
+    };
+  }
+  return { kind: "complete", patterns: patterns.map(({ value }) => value) };
+}
+
+function parseWorkspacePattern(value: unknown): ParsedPattern {
+  if (typeof value !== "string" || value.trim() !== value || value.length === 0) {
+    return {
+      kind: "unavailable",
+      reason: "Workspace patterns must be non-empty strings without surrounding whitespace.",
+    };
+  }
+
+  const negative = value.startsWith("!");
+  const normalized = normalizeWorkspacePattern(negative ? value.slice(1) : value);
+  if (!normalized) {
+    return {
+      kind: "unavailable",
+      reason: `Unsupported workspace pattern: \`${value}\`. Supported patterns use literal path segments, \`*\`, \`**\`, and an optional leading \`!\`.`,
+    };
+  }
+  return {
+    kind: "complete",
+    pattern: { value: `${negative ? "!" : ""}${normalized}`, negative },
+  };
+}
+
+function reincludesAfterExclusion(patterns: readonly { readonly negative: boolean }[]): boolean {
+  let sawExclusion = false;
+  for (const pattern of patterns) {
+    if (!pattern.negative && sawExclusion) return true;
+    if (pattern.negative) sawExclusion = true;
+  }
+  return false;
+}
+
+/** Normalize only path spelling; matching itself remains owned by Node's native glob. */
+function normalizeWorkspacePattern(pattern: string): string | null {
+  const withoutDotPrefix = pattern.replace(/^\.\//, "").replace(/\/$/, "");
+  if (!withoutDotPrefix || path.isAbsolute(withoutDotPrefix) || withoutDotPrefix.includes("\\")) {
+    return null;
+  }
+  if (withoutDotPrefix.split("/").some((segment) => segment === ".." || segment.length === 0)) {
+    return null;
+  }
+  if (
+    ["?", "[", "]", "{", "}", "(", ")", "!"].some((token) => withoutDotPrefix.includes(token)) ||
+    withoutDotPrefix.includes("***")
+  ) {
+    return null;
+  }
+  return withoutDotPrefix;
+}
+
+function ancestors(start: string): string[] {
+  const directories: string[] = [];
+  let current = start;
+  while (true) {
+    directories.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) return directories;
+    current = parent;
+  }
+}

package/src/analysis/{coverage/coverage-warnings.ts → capability/capability-warnings.ts}

@@ -1,8 +1,8 @@
 /**
- * Coverage warning evaluation for degraded structural and semantic coverage.
+ * Capability Warning evaluation for reduced semantic and structural analysis.
  *
  * Normalizes LSP startup state, Tree-sitter health, and deprecated config keys
- * into a structured warning report consumed by chat warnings, /supi-ci-status,
+ * into a structured report consumed by the startup notice, /supi-ci-status,
  * and code_health.
  */
 
@@ -10,42 +10,37 @@ import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
 import { loadSupiConfigForScope } from "@mrclrchtr/supi-core/config";
 import { getDeprecatedLspKeys, loadConfig, scanMissingServers } from "@mrclrchtr/supi-lsp/api";
 
-export interface CoverageWarning {
+/** One actionable warning about reduced Code intelligence capability. */
+export interface CapabilityWarning {
   type: "deprecated-key" | "language-disabled" | "missing-server" | "structural-unavailable";
   message: string;
   language?: string;
   detail?: string;
 }
 
-export interface CoverageWarningReport {
+/** Current Capability Warnings and their aggregate presence flag. */
+export interface CapabilityWarningReport {
   hasWarnings: boolean;
-  warnings: CoverageWarning[];
+  warnings: CapabilityWarning[];
 }
 
-export interface CoverageMissingServerSource {
+/** Minimal LSP-controller surface needed to discover missing servers. */
+export interface CapabilityWarningMissingServerSource {
   getMissingServers(): Array<{ name: string; command: string; foundExtensions?: string[] }>;
 }
 
-/** Input needed to evaluate coverage. */
-export interface CoverageEvalInput {
+/** Current runtime/config facts needed to evaluate Capability Warnings. */
+export interface CapabilityWarningInput {
   deprecatedKeys: ReturnType<typeof getDeprecatedLspKeys>;
   explicitlyDisabledLanguages: string[];
   missingServers: Array<{ name: string; command: string; foundExtensions: string[] }>;
   structuralState: { kind: string; reason?: string };
 }
 
-// ── Evaluation ───────────────────────────────────────────────
+/** Evaluate current capability/configuration facts into a structured warning report. */
+export function evaluateCapabilityWarnings(input: CapabilityWarningInput): CapabilityWarningReport {
+  const warnings: CapabilityWarning[] = [];
 
-/**
- * Evaluate the current coverage state and return a structured warning report.
- *
- * Does not handle deduplication or grace period — callers are responsible
- * for managing emission timing through CoverageWarningState.
- */
-export function evaluateCoverageWarnings(input: CoverageEvalInput): CoverageWarningReport {
-  const warnings: CoverageWarning[] = [];
-
-  // 1. Deprecated keys
   if (input.deprecatedKeys.projectEnabled || input.deprecatedKeys.globalEnabled) {
     warnings.push({
       type: "deprecated-key",
@@ -61,16 +56,14 @@ export function evaluateCoverageWarnings(input: CoverageEvalInput): CoverageWarn
     });
   }
 
-  // 2. Explicitly disabled languages
-  for (const lang of input.explicitlyDisabledLanguages) {
+  for (const language of input.explicitlyDisabledLanguages) {
     warnings.push({
       type: "language-disabled",
-      language: lang,
-      message: `Semantic coverage reduced: "${lang}" servers are disabled via lsp.servers.${lang}.enabled: false`,
+      language,
+      message: `Semantic capability reduced: "${language}" servers are disabled via lsp.servers.${language}.enabled: false`,
     });
   }
 
-  // 3. Missing server binaries
   for (const server of input.missingServers) {
     warnings.push({
       type: "missing-server",
@@ -83,102 +76,73 @@ export function evaluateCoverageWarnings(input: CoverageEvalInput): CoverageWarn
     });
   }
 
-  // 4. Structural (Tree-sitter) failure
   if (input.structuralState.kind === "unavailable") {
     warnings.push({
       type: "structural-unavailable",
-      message: `Structural coverage unavailable: ${input.structuralState.reason ?? "Tree-sitter initialization failed"}`,
+      message: `Structural capability unavailable: ${input.structuralState.reason ?? "Tree-sitter initialization failed"}`,
     });
   }
 
   return { hasWarnings: warnings.length > 0, warnings };
 }
 
-// ── Session state (deduplication + grace period) ─────────────
-
-/**
- * Per-session state for managing warning emission timing and deduplication.
- */
-export class CoverageWarningState {
+/** Per-session state for warning grace-period timing and deduplication. */
+export class CapabilityWarningState {
   private lastWarningsHash: string | null = null;
   private forceEmitted = false;
-  private readonly startedAt: number;
-
-  constructor() {
-    this.startedAt = Date.now();
-  }
+  private readonly startedAt = Date.now();
 
   /**
-   * Return warnings that should be emitted to the user now.
+   * Return warnings that should be emitted now.
    *
-   * Deduplication is hash-based rather than once-per-session: if the
-   * warning set changes (e.g., a new missing server is detected), the
-   * new warnings are emitted. Identical sets are suppressed.
-   * - Respects grace period (no warnings before `gracePeriodMs` has elapsed)
-   * - An empty report (no warnings) does not consume emission state
+   * Changed warning sets may emit again; identical sets are suppressed. Empty
+   * reports do not consume emission state, and startup honors a grace period.
    */
   getPendingWarnings(
-    report: CoverageWarningReport,
+    report: CapabilityWarningReport,
     gracePeriodMs: number = 5_000,
-  ): CoverageWarning[] {
-    // Grace period: don't emit during initial pending/settling state
-    if (Date.now() - this.startedAt < gracePeriodMs) {
-      return [];
-    }
-
-    if (!report.hasWarnings || report.warnings.length === 0) {
-      return [];
-    }
-
+  ): CapabilityWarning[] {
+    if (Date.now() - this.startedAt < gracePeriodMs) return [];
+    if (!report.hasWarnings || report.warnings.length === 0) return [];
     if (this.forceEmitted) return [];
 
     const nextHash = this.computeHash(report);
-    if (nextHash === this.lastWarningsHash) {
-      return [];
-    }
+    if (nextHash === this.lastWarningsHash) return [];
 
     this.lastWarningsHash = nextHash;
     return report.warnings;
   }
 
-  /** Check whether a warning has already been emitted this session. */
+  /** Whether any warning set has been emitted in this session. */
   get hasEmitted(): boolean {
     return this.lastWarningsHash !== null;
   }
 
-  /** Force the state to consider warnings as already emitted. Useful for testing. */
+  /** Force warnings to be considered emitted. Useful for tests. */
   markEmitted(): void {
     this.forceEmitted = true;
     this.lastWarningsHash = "emitted";
   }
 
-  /** Reset the session state. */
+  /** Reset warning emission state. */
   reset(): void {
     this.forceEmitted = false;
     this.lastWarningsHash = null;
   }
 
-  private computeHash(report: CoverageWarningReport): string {
+  private computeHash(report: CapabilityWarningReport): string {
     return report.warnings
-      .map((w) => `${w.type}:${w.language ?? ""}:${w.message}`)
-      .sort((a, b) => a.localeCompare(b))
+      .map((warning) => `${warning.type}:${warning.language ?? ""}:${warning.message}`)
+      .sort((left, right) => left.localeCompare(right))
       .join("|");
   }
 }
 
-// ── Runtime state gathering ─────────────────────────────────
-
-/**
- * Gather the coverage evaluation input from current runtime state.
- *
- * Reads deprecated keys from supi-lsp, structural state from the
- * workspace runtime, and explicitly disabled languages / missing server
- * info from the LSP controller or a config-based fallback scan.
- */
-export function gatherCoverageEvalInput(
+/** Gather current runtime/config facts for Capability Warning evaluation. */
+export function gatherCapabilityWarningInput(
   cwd: string,
-  lspController: CoverageMissingServerSource | null,
-): CoverageEvalInput {
+  lspController: CapabilityWarningMissingServerSource | null,
+): CapabilityWarningInput {
   const deprecatedKeys = getDeprecatedLspKeys(cwd);
   const structuralState = getDefaultWorkspaceRuntime().getWorkspace(cwd).structural.state;
   const explicitlyDisabledLanguages = detectExplicitlyDisabledLanguages(cwd);
@@ -204,7 +168,6 @@ function normalizeMissingServers(
   }));
 }
 
-/** Read raw scoped config to find languages with `servers.<lang>.enabled: false`. */
 function detectExplicitlyDisabledLanguages(cwd: string): string[] {
   const disabled = new Set<string>();
   for (const scope of ["project", "global"] as const) {
@@ -216,8 +179,8 @@ function detectExplicitlyDisabledLanguages(cwd: string): string[] {
     );
     const servers = (raw as { servers?: Record<string, { enabled?: boolean }> }).servers;
     if (!servers) continue;
-    for (const [name, srv] of Object.entries(servers)) {
-      if (srv.enabled === false) disabled.add(name);
+    for (const [name, server] of Object.entries(servers)) {
+      if (server.enabled === false) disabled.add(name);
     }
   }
   return [...disabled].sort();