@wkronmiller/lisa 0.1.0

package/src/spec/loader.ts

@@ -0,0 +1,174 @@
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join, relative } from "path";
+
+import { parseSpecConfig, parseSpecDocument, parseSpecEnvironmentConfig } from "./parser";
+import type { LoadedSpecWorkspace, ValidationIssue } from "./types";
+import { validateEnvironmentConfig, validateLoadedSpecWorkspace, validateSpecConfig, validateSpecDocument } from "./validator";
+import { listEffectiveWorkspaceFiles, resolveWorkspaceLayout, resolveWorkspaceRoot } from "./workspace";
+
+function decodeOutput(bytes: Uint8Array<ArrayBufferLike>): string {
+  return new TextDecoder().decode(bytes);
+}
+
+function loadDirectoryFiles(path: string, predicate: (entry: string) => boolean): string[] {
+  if (!existsSync(path)) {
+    return [];
+  }
+
+  return readdirSync(path).filter(predicate).sort().map((entry) => join(path, entry));
+}
+
+function parseFileError(path: string, error: unknown): ValidationIssue {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    path,
+    severity: "error",
+    message,
+  };
+}
+
+function runGitCommand(
+  workspacePath: string,
+  args: string[],
+  options: { allowFailure?: boolean } = {},
+): { stdout: string; stderr: string; exitCode: number } {
+  const proc = Bun.spawnSync({
+    cmd: ["git", ...args],
+    cwd: workspacePath,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const stdout = decodeOutput(proc.stdout);
+  const stderr = decodeOutput(proc.stderr);
+  if (proc.exitCode !== 0 && !options.allowFailure) {
+    throw new Error(stderr.trim() || `git ${args.join(" ")} failed with exit code ${proc.exitCode}.`);
+  }
+
+  return {
+    stdout,
+    stderr,
+    exitCode: proc.exitCode,
+  };
+}
+
+function listSpecFilesAtRef(workspacePath: string, ref: string): string[] {
+  const result = runGitCommand(workspacePath, ["ls-tree", "-r", "--name-only", ref, "--", ".specs"], { allowFailure: true });
+  if (result.exitCode !== 0) {
+    return [];
+  }
+
+  return result.stdout
+    .split("\n")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+function readSpecFileAtRef(workspacePath: string, ref: string, relativePath: string): string | undefined {
+  const result = runGitCommand(workspacePath, ["show", `${ref}:${relativePath}`], { allowFailure: true });
+  return result.exitCode === 0 ? result.stdout : undefined;
+}
+
+function loadWorkspaceFromPaths(
+  layout: ReturnType<typeof resolveWorkspaceLayout>,
+  configPath: string,
+  documentPaths: string[],
+  environmentPaths: string[],
+  readFile: (path: string) => string | undefined,
+): LoadedSpecWorkspace {
+  const issues: ValidationIssue[] = [];
+  let config: LoadedSpecWorkspace["config"];
+
+  const configContent = readFile(configPath);
+  if (configContent !== undefined) {
+    try {
+      config = parseSpecConfig(configPath, configContent);
+      issues.push(...validateSpecConfig(config));
+    } catch (error) {
+      issues.push(parseFileError(configPath, error));
+    }
+  }
+
+  const documents: LoadedSpecWorkspace["documents"] = [];
+  for (const filePath of documentPaths.sort()) {
+    try {
+      const content = readFile(filePath);
+      if (content === undefined) {
+        continue;
+      }
+      const document = parseSpecDocument(filePath, content);
+      documents.push(document);
+      issues.push(...validateSpecDocument(document));
+    } catch (error) {
+      issues.push(parseFileError(filePath, error));
+    }
+  }
+
+  const environments: LoadedSpecWorkspace["environments"] = [];
+  for (const filePath of environmentPaths.sort()) {
+    try {
+      const content = readFile(filePath);
+      if (content === undefined) {
+        continue;
+      }
+      const environment = parseSpecEnvironmentConfig(filePath, content);
+      environments.push(environment);
+      issues.push(...validateEnvironmentConfig(environment));
+    } catch (error) {
+      issues.push(parseFileError(filePath, error));
+    }
+  }
+
+  issues.push(...validateLoadedSpecWorkspace({ workspacePath: layout.workspacePath, config, documents, environments }));
+
+  return {
+    workspacePath: layout.workspacePath,
+    storageMode: layout.storageMode,
+    specRoot: layout.repoSpecRoot,
+    repoSpecRoot: layout.repoSpecRoot,
+    worktreeSpecRoot: layout.worktreeSpecRoot,
+    configPath,
+    localConfigRoot: layout.localConfigRoot,
+    runtimeRoot: layout.runtimeRoot,
+    snapshotRoot: layout.snapshotRoot,
+    metadataPath: layout.metadataPath,
+    globalPackRoots: layout.globalPackRoots,
+    config,
+    environments,
+    documents,
+    issues,
+  };
+}
+
+export function loadSpecWorkspace(cwd = process.cwd()): LoadedSpecWorkspace {
+  const layout = resolveWorkspaceLayout(cwd);
+  const effective = listEffectiveWorkspaceFiles(layout);
+  return loadWorkspaceFromPaths(
+    layout,
+    effective.configPath ?? layout.repoConfigPath,
+    effective.documentPaths,
+    effective.environmentPaths,
+    (filePath) => (existsSync(filePath) ? readFileSync(filePath, "utf8") : undefined),
+  );
+}
+
+export function loadSpecWorkspaceAtRef(ref: string, cwd = process.cwd()): LoadedSpecWorkspace {
+  const layout = resolveWorkspaceLayout(cwd);
+  if (layout.storageMode === "external") {
+    throw new Error("External Lisa workspaces do not support loading specs by git revision yet.");
+  }
+  const workspacePath = resolveWorkspaceRoot(cwd);
+  const paths = listSpecFilesAtRef(workspacePath, ref);
+
+  return loadWorkspaceFromPaths(
+    layout,
+    layout.repoConfigPath,
+    paths
+      .filter((path) => path.startsWith(".specs/backend/") || path.startsWith(".specs/frontend/"))
+      .map((path) => join(workspacePath, path)),
+    paths
+      .filter((path) => path.startsWith(".specs/environments/") && (path.endsWith(".yaml") || path.endsWith(".yml")))
+      .map((path) => join(workspacePath, path)),
+    (filePath) => readSpecFileAtRef(workspacePath, ref, relative(workspacePath, filePath).split("\\").join("/")),
+  );
+}

package/src/spec/local-config.ts

@@ -0,0 +1,59 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+
+export interface LocalConfig {
+  harness?: string;
+}
+
+const LOCAL_CONFIG_FILENAME = "config.local.yaml";
+
+export function localConfigPath(specRoot: string): string {
+  return join(specRoot, LOCAL_CONFIG_FILENAME);
+}
+
+export function loadLocalConfig(specRoot: string): LocalConfig {
+  const path = localConfigPath(specRoot);
+  if (!existsSync(path)) {
+    return {};
+  }
+
+  const raw = Bun.YAML.parse(readFileSync(path, "utf8"));
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return {};
+  }
+
+  const record = raw as Record<string, unknown>;
+  return {
+    harness: typeof record.harness === "string" ? record.harness : undefined,
+  };
+}
+
+export function saveLocalConfig(specRoot: string, config: LocalConfig): void {
+  const path = localConfigPath(specRoot);
+  if (!config.harness) {
+    return;
+  }
+
+  mkdirSync(specRoot, { recursive: true });
+  writeFileSync(path, Bun.YAML.stringify({ harness: config.harness }));
+}
+
+export function resetLocalConfig(specRoot: string): boolean {
+  const path = localConfigPath(specRoot);
+  if (!existsSync(path)) {
+    return false;
+  }
+
+  const { rmSync } = require("fs");
+  rmSync(path);
+  return true;
+}
+
+export function resolveLocalOverrides(specRoot: string): LocalConfig {
+  const envHarness = process.env.LISA_HARNESS;
+  const local = loadLocalConfig(specRoot);
+
+  return {
+    harness: envHarness || local.harness,
+  };
+}

package/src/spec/parser.ts

@@ -0,0 +1,226 @@
+import { basename } from "path";
+
+import { resolveExtensionKindForPath } from "./extensions/registry";
+import type {
+  ParsedAgentGuidanceConfig,
+  ParsedEnvironmentConfig,
+  ParsedHarnessConfig,
+  ParsedMarkdownSection,
+  ParsedSpecConfig,
+  ParsedSpecDocument,
+  ParsedStageProfile,
+  SpecArea,
+} from "./types";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeNewlines(content: string): string {
+  return content.replace(/\r\n/g, "\n");
+}
+
+function parseYamlObject(source: string, path: string): Record<string, unknown> {
+  try {
+    const parsed = Bun.YAML.parse(source);
+    if (parsed === null) {
+      return {};
+    }
+
+    if (!isRecord(parsed)) {
+      throw new Error("YAML document must parse to an object.");
+    }
+
+    return parsed;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse YAML in ${path}: ${message}`);
+  }
+}
+
+function inferSpecArea(path: string): SpecArea | undefined {
+  const match = path.match(/[\\/]\.specs[\\/](backend|frontend)[\\/]/);
+  return match?.[1] as SpecArea | undefined;
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+function parseStageProfile(value: unknown): ParsedStageProfile {
+  const raw = isRecord(value) ? value : {};
+  return {
+    harness: typeof raw.harness === "string" ? raw.harness : undefined,
+    model: typeof raw.model === "string" ? raw.model : undefined,
+    allowEdits: typeof raw.allow_edits === "boolean" ? raw.allow_edits : undefined,
+    raw,
+  };
+}
+
+function parseHarnessConfig(value: unknown): ParsedHarnessConfig {
+  const raw = isRecord(value) ? value : {};
+  return {
+    command: typeof raw.command === "string" ? raw.command : undefined,
+    args: isStringArray(raw.args) ? raw.args : [],
+    raw,
+  };
+}
+
+function parseAgentGuidanceConfig(value: unknown): ParsedAgentGuidanceConfig | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const raw = isRecord(value) ? value : {};
+  const targets = isStringArray(raw.targets) ? raw.targets : undefined;
+  return {
+    enabled: typeof raw.enabled === "boolean" ? raw.enabled : undefined,
+    target: typeof raw.target === "string" ? raw.target : undefined,
+    targets,
+    raw,
+  };
+}
+
+function extractFrontmatter(document: string, path: string): { frontmatter: Record<string, unknown>; body: string } {
+  if (!document.startsWith("---\n")) {
+    return { frontmatter: {}, body: document.trim() };
+  }
+
+  const match = document.match(/^---\n([\s\S]*?)\n---(?:\n([\s\S]*))?$/);
+  if (!match) {
+    throw new Error(`Failed to parse YAML frontmatter in ${path}: missing closing delimiter.`);
+  }
+
+  return {
+    frontmatter: parseYamlObject(match[1] ?? "", path),
+    body: (match[2] ?? "").trim(),
+  };
+}
+
+export function parseMarkdownSections(body: string): ParsedMarkdownSection[] {
+  const normalized = normalizeNewlines(body);
+  const lines = normalized.split("\n");
+  const sections: ParsedMarkdownSection[] = [];
+  let current: { title: string; level: number; lines: string[] } | undefined;
+  let fenceState: { marker: string; length: number } | undefined;
+
+  for (const line of lines) {
+    const fenceMatch = line.match(/^([`~]{3,})(.*)$/);
+    if (fenceMatch) {
+      const fence = fenceMatch[1];
+      const marker = fence[0];
+      const trailingText = fenceMatch[2].trim();
+      if (!fenceState) {
+        fenceState = { marker, length: fence.length };
+      } else if (fenceState.marker === marker && fence.length >= fenceState.length && trailingText.length === 0) {
+        fenceState = undefined;
+      }
+
+      if (current) {
+        current.lines.push(line);
+      }
+      continue;
+    }
+
+    if (fenceState) {
+      if (current) {
+        current.lines.push(line);
+      }
+      continue;
+    }
+
+    const headingMatch = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (headingMatch) {
+      if (current) {
+        sections.push({
+          title: current.title,
+          level: current.level,
+          content: current.lines.join("\n").trim(),
+        });
+      }
+
+      current = {
+        title: headingMatch[2],
+        level: headingMatch[1].length,
+        lines: [],
+      };
+      continue;
+    }
+
+    if (current) {
+      current.lines.push(line);
+    }
+  }
+
+  if (current) {
+    sections.push({
+      title: current.title,
+      level: current.level,
+      content: current.lines.join("\n").trim(),
+    });
+  }
+
+  return sections;
+}
+
+export function parseSpecDocument(path: string, content: string): ParsedSpecDocument {
+  const normalized = normalizeNewlines(content);
+  const { frontmatter, body } = extractFrontmatter(normalized, path);
+  const filename = basename(path);
+  const extensionKind = resolveExtensionKindForPath(filename);
+  const kind = !extensionKind ? "base" : extensionKind === "benchmark" ? "benchmark" : "extension";
+
+  return {
+    path,
+    filename,
+    area: inferSpecArea(path),
+    kind,
+    extensionKind,
+    id: typeof frontmatter.id === "string" ? frontmatter.id : undefined,
+    status: typeof frontmatter.status === "string" ? frontmatter.status : undefined,
+    frontmatter,
+    body,
+    sections: parseMarkdownSections(body),
+  };
+}
+
+export function parseSpecConfig(path: string, content: string): ParsedSpecConfig {
+  const raw = parseYamlObject(normalizeNewlines(content), path);
+  const defaults = isRecord(raw.default_stage_profiles) ? raw.default_stage_profiles : {};
+  const profilesRaw = isRecord(raw.profiles) ? raw.profiles : {};
+  const harnessesRaw = isRecord(raw.harnesses) ? raw.harnesses : {};
+
+  const defaultStageProfiles = Object.fromEntries(
+    Object.entries(defaults).filter(([, value]) => typeof value === "string"),
+  ) as ParsedSpecConfig["defaultStageProfiles"];
+
+  const profiles = Object.fromEntries(
+    Object.entries(profilesRaw).map(([name, value]) => [name, parseStageProfile(value)]),
+  );
+
+  const harnesses = Object.fromEntries(
+    Object.entries(harnessesRaw).map(([name, value]) => [name, parseHarnessConfig(value)]),
+  );
+
+  return {
+    path,
+    raw,
+    defaultStageProfiles,
+    profiles,
+    harnesses,
+    agentGuidance: parseAgentGuidanceConfig(raw.agent_guidance),
+  };
+}
+
+export function parseSpecEnvironmentConfig(path: string, content: string): ParsedEnvironmentConfig {
+  const raw = parseYamlObject(normalizeNewlines(content), path);
+
+  return {
+    path,
+    name: typeof raw.name === "string" ? raw.name : undefined,
+    runtime: isRecord(raw.runtime) ? raw.runtime : undefined,
+    resources: isRecord(raw.resources) ? raw.resources : undefined,
+    notes: typeof raw.notes === "string" ? raw.notes : undefined,
+    raw,
+  };
+}

package/src/spec/path-utils.ts

@@ -0,0 +1,73 @@
+export function normalizeRelativePath(path: string): string {
+  return path.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+/g, "/").replace(/^\//, "");
+}
+
+export function hasGlobMagic(pattern: string): boolean {
+  return /[*?[]/.test(pattern);
+}
+
+export function isSafeContextPattern(pattern: string): boolean {
+  const normalized = normalizeRelativePath(pattern);
+  if (pattern.startsWith("/") || pattern.startsWith("\\") || normalized.startsWith("//") || /^[A-Za-z]:\//.test(normalized)) {
+    return false;
+  }
+
+  return !normalized.split("/").some((segment) => segment === "..");
+}
+
+export function escapeRegExp(text: string): string {
+  return text.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+
+export function globToRegExp(pattern: string): RegExp {
+  const normalized = normalizeRelativePath(pattern);
+  let source = "^";
+
+  for (let index = 0; index < normalized.length; index += 1) {
+    const character = normalized[index];
+    const next = normalized[index + 1];
+
+    if (character === "*") {
+      if (next === "*") {
+        if (normalized[index + 2] === "/") {
+          source += "(?:.*/)?";
+          index += 2;
+        } else {
+          source += ".*";
+          index += 1;
+        }
+      } else {
+        source += "[^/]*";
+      }
+      continue;
+    }
+
+    if (character === "?") {
+      source += "[^/]";
+      continue;
+    }
+
+    if (character === "[") {
+      const closingIndex = normalized.indexOf("]", index + 1);
+      if (closingIndex > index + 1) {
+        let classContent = normalized.slice(index + 1, closingIndex);
+        let negate = false;
+        if (classContent.startsWith("!") || classContent.startsWith("^")) {
+          negate = true;
+          classContent = classContent.slice(1);
+        }
+
+        if (classContent.length > 0) {
+          source += `${negate ? "[^" : "["}${classContent.replace(/\\/g, "\\\\")}]`;
+          index = closingIndex;
+          continue;
+        }
+      }
+    }
+
+    source += escapeRegExp(character);
+  }
+
+  source += "$";
+  return new RegExp(source);
+}