vigiles 2.0.0

package/src/compile.ts

@@ -0,0 +1,691 @@
+/**
+ * vigiles v2 — Compiler: spec → markdown.
+ *
+ * Reads .spec.ts files, validates references, and produces
+ * markdown instruction files with integrity hashes.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, dirname, basename } from "node:path";
+
+import type {
+  ClaudeSpec,
+  SkillSpec,
+  Rule,
+  InstructionFragment,
+} from "./spec.js";
+
+import { checkLinterRule, extractLinterName } from "./linters.js";
+import type { LinterCheckResult } from "./linters.js";
+
+// ---------------------------------------------------------------------------
+// Hash utilities
+// ---------------------------------------------------------------------------
+
+const HASH_RE =
+  /^<!-- vigiles:sha256:([a-f0-9]+) compiled from (.+) -->\r?\n\r?\n?/;
+
+/** @internal Compute SHA-256 hash of content (excluding any existing hash line). */
+export function computeHash(content: string): string {
+  const body = content.replace(HASH_RE, "");
+  return createHash("sha256").update(body).digest("hex").slice(0, 16);
+}
+
+/** @internal Prepend a hash comment to compiled content. */
+export function addHash(content: string, specFile: string): string {
+  const hash = computeHash(content);
+  return `<!-- vigiles:sha256:${hash} compiled from ${specFile} -->\n\n${content}`;
+}
+
+/** @internal Check if a file's hash matches its content. Returns null if no hash found. */
+export function verifyHash(
+  content: string,
+): { valid: boolean; specFile: string } | null {
+  const match = content.match(HASH_RE);
+  if (!match) return null;
+  const expectedHash = match[1];
+  const specFile = match[2];
+  const body = content.replace(HASH_RE, "");
+  const actualHash = createHash("sha256")
+    .update(body)
+    .digest("hex")
+    .slice(0, 16);
+  return { valid: actualHash === expectedHash, specFile };
+}
+
+// ---------------------------------------------------------------------------
+// Token estimation
+// ---------------------------------------------------------------------------
+
+/**
+ * Estimate token count for a string.
+ *
+ * Uses the ~4 characters per token heuristic (accurate within ~10% for
+ * English text and code). Swap in a real BPE tokenizer (tiktoken, gpt-tokenizer)
+ * for exact counts if needed.
+ */
+/** @internal */ export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+// ---------------------------------------------------------------------------
+// Validation errors
+// ---------------------------------------------------------------------------
+
+export interface CompileError {
+  type:
+    | "stale-file"
+    | "stale-command"
+    | "stale-ref"
+    | "invalid-rule"
+    | "budget-exceeded"
+    | "section-too-long"
+    | "section-has-header"
+    | "reserved-section-key"
+    | "spec-name-mismatch";
+  message: string;
+  path?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Reference validation
+// ---------------------------------------------------------------------------
+
+function validateFileRef(
+  filePath: string,
+  basePath: string,
+): CompileError | null {
+  const resolved = resolve(basePath, filePath);
+  if (!existsSync(resolved)) {
+    return {
+      type: "stale-file",
+      message: `File not found: "${filePath}"`,
+      path: filePath,
+    };
+  }
+  return null;
+}
+
+function readPackageScripts(basePath: string): Record<string, string> | null {
+  const pkgPath = resolve(basePath, "package.json");
+  if (!existsSync(pkgPath)) return null;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
+      scripts?: Record<string, string>;
+    };
+    return pkg.scripts ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function validateCommandRef(
+  command: string,
+  basePath: string,
+): CompileError | null {
+  // Check "npm run <script>" or "npm <script>" against package.json
+  const npmRunMatch = command.match(/^npm\s+run\s+(\S+)/);
+  const npmMatch = command.match(/^npm\s+(test|start|build|pretest)\b/);
+  const scriptName = npmRunMatch?.[1] ?? npmMatch?.[1];
+  if (!scriptName) return null;
+
+  const scripts = readPackageScripts(basePath);
+  if (!scripts) return null;
+
+  if (!scripts[scriptName]) {
+    return {
+      type: "stale-command",
+      message: `Script "${scriptName}" not found in package.json`,
+      path: command,
+    };
+  }
+  return null;
+}
+
+function validateRefs(
+  fragments: InstructionFragment[],
+  basePath: string,
+): CompileError[] {
+  const errors: CompileError[] = [];
+  for (const fragment of fragments) {
+    if (typeof fragment === "string") continue;
+    const r = fragment;
+    switch (r._ref) {
+      case "file": {
+        const err = validateFileRef(r.path, basePath);
+        if (err) errors.push(err);
+        break;
+      }
+      case "cmd": {
+        const err = validateCommandRef(r.command, basePath);
+        if (err) errors.push(err);
+        break;
+      }
+      case "skill": {
+        const err = validateFileRef(r.path, basePath);
+        if (err) {
+          errors.push({
+            type: "stale-ref",
+            message: `Skill not found: "${r.path}"`,
+            path: r.path,
+          });
+        }
+        break;
+      }
+    }
+  }
+  return errors;
+}
+
+function renderFragment(fragment: InstructionFragment): string {
+  if (typeof fragment === "string") return fragment;
+  const r = fragment;
+  switch (r._ref) {
+    case "file":
+      return `\`${r.path}\``;
+    case "cmd":
+      return `\`${r.command}\``;
+    case "skill":
+      return `[${basename(dirname(r.path))}](${r.path})`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Compile CLAUDE.md spec → markdown
+// ---------------------------------------------------------------------------
+
+function compileRule(id: string, rule: Rule): string {
+  const title = id
+    .replace(/[-_]/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+
+  switch (rule._kind) {
+    case "enforce":
+      return [
+        `### ${title}`,
+        "",
+        `**Enforced by:** \`${rule.linterRule}\``,
+        `**Why:** ${rule.why}`,
+      ].join("\n");
+
+    case "guidance":
+      return [`### ${title}`, "", `**Guidance only** — ${rule.text}`].join(
+        "\n",
+      );
+
+    default: {
+      // Unknown rule kind — legacy compiled JS spec artifacts, JS caller,
+      // or cast bypass. Fail loudly rather than silently dropping the
+      // rule from output, which would remove constraints without any
+      // compile error.
+      const unknown = (rule as { _kind?: unknown })._kind;
+      throw new Error(
+        `Unknown rule kind "${String(unknown)}" for rule "${id}". ` +
+          `Expected "enforce" or "guidance". Runtime data is out of sync with the Rule type.`,
+      );
+    }
+  }
+}
+
+export interface CompileClaudeResult {
+  markdown: string;
+  errors: CompileError[];
+  linterResults: LinterCheckResult[];
+  /** Estimated token count of compiled output (~4 chars/token). */
+  tokens: number;
+  /** All targets from the spec (for multi-target compilation). */
+  targets: string[];
+}
+
+export interface CompileClaudeOptions {
+  basePath?: string;
+  specFile?: string;
+  /** Maximum number of rules allowed. Compilation fails if exceeded. */
+  maxRules?: number;
+  /** Maximum estimated tokens for compiled output. */
+  maxTokens?: number;
+  /** Maximum lines per prose section. Forces splitting into named sections. */
+  maxSectionLines?: number;
+  /** Skip config-enabled checks, only verify rule exists in catalog. */
+  catalogOnly?: boolean;
+  /** Custom linter configs (rulesDir). */
+  linters?: Record<string, { rulesDir?: string | string[] }>;
+  /** Global kill switch: skip ALL linter verification. */
+  verifyLinters?: boolean;
+  /** Per-linter verification mode: true (full), "catalog-only", or false (skip). */
+  linterModes?: Record<string, boolean | "catalog-only">;
+}
+
+// ---------------------------------------------------------------------------
+// compileClaude section helpers
+// ---------------------------------------------------------------------------
+
+interface SectionResult {
+  lines: string[];
+  errors: CompileError[];
+}
+
+function validateSectionContent(
+  name: string,
+  text: string,
+  maxSectionLines?: number,
+): CompileError[] {
+  const errors: CompileError[] = [];
+  const contentLines = text.split("\n");
+
+  // Reject markdown headers inside sections — sections compile to ## headings,
+  // so raw # headers break document structure and signal pasted-in content.
+  // Skip lines inside fenced code blocks (``` or ~~~).
+  let inFence = false;
+  for (const line of contentLines) {
+    if (/^ {0,3}(`{3,}|~{3,})/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    if (/^ {0,3}#{1,2}\s/.test(line)) {
+      errors.push({
+        type: "section-has-header",
+        message: `Section "${name}" contains a markdown header ("${line.trim().slice(0, 60)}"). Break into separate named sections instead.`,
+      });
+      break;
+    }
+  }
+
+  if (maxSectionLines && contentLines.length > maxSectionLines) {
+    errors.push({
+      type: "section-too-long",
+      message: `Section "${name}" is ${String(contentLines.length)} lines (max ${String(maxSectionLines)}). Split into smaller named sections.`,
+    });
+  }
+
+  return errors;
+}
+
+const RESERVED_SECTION_KEYS = new Set([
+  "commands",
+  "keyFiles",
+  "key-files",
+  "key_files",
+  "rules",
+]);
+
+function compileSectionsSection(
+  spec: ClaudeSpec,
+  basePath: string,
+  maxSectionLines?: number,
+): SectionResult {
+  if (!spec.sections) return { lines: [], errors: [] };
+  const lines: string[] = [];
+  const errors: CompileError[] = [];
+  for (const [name, content] of Object.entries(spec.sections)) {
+    // #4: reject reserved section keys that clash with structured fields
+    if (RESERVED_SECTION_KEYS.has(name)) {
+      errors.push({
+        type: "reserved-section-key",
+        message: `Section key "${name}" is reserved — use the dedicated \`${name}\` field on the spec instead.`,
+      });
+    }
+    const heading = name.charAt(0).toUpperCase() + name.slice(1);
+    if (typeof content === "string") {
+      errors.push(...validateSectionContent(name, content, maxSectionLines));
+      lines.push(`## ${heading}\n\n${content.trim()}`);
+    } else {
+      errors.push(...validateRefs(content, basePath));
+      const rendered = content.map(renderFragment).join("");
+      errors.push(...validateSectionContent(name, rendered, maxSectionLines));
+      lines.push(`## ${heading}\n\n${rendered.trim()}`);
+    }
+  }
+  return { lines, errors };
+}
+
+function compileKeyFilesSection(
+  spec: ClaudeSpec,
+  basePath: string,
+): SectionResult {
+  if (!spec.keyFiles) return { lines: [], errors: [] };
+  const lines = ["## Key Files", ""];
+  const errors: CompileError[] = [];
+  for (const [filePath, desc] of Object.entries(spec.keyFiles)) {
+    lines.push(`- \`${filePath}\` — ${desc}`);
+    const err = validateFileRef(filePath, basePath);
+    if (err) errors.push(err);
+  }
+  return { lines: [lines.join("\n")], errors };
+}
+
+function compileCommandsSection(
+  spec: ClaudeSpec,
+  basePath: string,
+): SectionResult {
+  if (!spec.commands) return { lines: [], errors: [] };
+  const lines = ["## Commands", ""];
+  const errors: CompileError[] = [];
+  for (const [command, desc] of Object.entries(spec.commands)) {
+    lines.push(`- \`${command}\` — ${desc}`);
+    const err = validateCommandRef(command, basePath);
+    if (err) errors.push(err);
+  }
+  return { lines: [lines.join("\n")], errors };
+}
+
+/**
+ * Determine if a rule should be verified, checking three levels:
+ * 1. Per-rule: enforce("...", "...", { verify: false })
+ * 2. Global: options.verifyLinters === false
+ * 3. Per-linter: options.linterModes[linterName] === false
+ */
+function shouldVerifyRule(
+  rule: { linterRule: string; verify: boolean },
+  options: CompileClaudeOptions,
+): boolean {
+  if (!rule.verify) return false;
+  if (options.verifyLinters === false) return false;
+  const linterName = extractLinterName(rule.linterRule);
+  const linterMode = options.linterModes?.[linterName];
+  if (linterMode === false) return false;
+  return true;
+}
+
+interface RulesSectionResult extends SectionResult {
+  linterResults: LinterCheckResult[];
+}
+
+function compileRulesSection(
+  spec: ClaudeSpec,
+  basePath: string,
+  options: CompileClaudeOptions,
+): RulesSectionResult {
+  const ruleEntries = Object.entries(spec.rules);
+  if (ruleEntries.length === 0) {
+    return { lines: [], errors: [], linterResults: [] };
+  }
+  const ruleLines = ["## Rules"];
+  const errors: CompileError[] = [];
+  const linterResults: LinterCheckResult[] = [];
+
+  for (const [id, rule] of ruleEntries) {
+    ruleLines.push("");
+    ruleLines.push(compileRule(id, rule));
+    if (rule._kind === "enforce") {
+      const shouldVerify = shouldVerifyRule(rule, options);
+      if (!shouldVerify) continue;
+
+      const linterName = extractLinterName(rule.linterRule);
+      const linterMode = options.linterModes?.[linterName];
+      const catalogOnly = options.catalogOnly || linterMode === "catalog-only";
+
+      const result = checkLinterRule(rule.linterRule, basePath, {
+        catalogOnly,
+        linters: options.linters,
+      });
+      linterResults.push(result);
+      if (!result.exists) {
+        errors.push({
+          type: "invalid-rule",
+          message:
+            result.error ??
+            `Rule "${rule.linterRule}" not found in ${result.linter}`,
+          path: rule.linterRule,
+        });
+      } else if (result.enabled === "disabled") {
+        errors.push({
+          type: "invalid-rule",
+          message: `Rule "${result.rule}" exists but is disabled in ${result.linter} config`,
+          path: rule.linterRule,
+        });
+      }
+    }
+  }
+  return { lines: [ruleLines.join("\n")], errors, linterResults };
+}
+
+// ---------------------------------------------------------------------------
+// compileClaude
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a ClaudeSpec into markdown.
+ *
+ * Returns the compiled markdown, validation errors, and linter check results.
+ * The markdown is generated even if there are errors (with warnings).
+ */
+export function compileClaude(
+  spec: ClaudeSpec,
+  options: CompileClaudeOptions = {},
+): CompileClaudeResult {
+  const targets = spec.target ?? "CLAUDE.md";
+  const target = Array.isArray(targets) ? targets[0] : targets;
+  const basePath = options.basePath ?? process.cwd();
+  const specFile = options.specFile ?? `${target}.spec.ts`;
+  const errors: CompileError[] = [];
+  const sections: string[] = [`# ${target}`];
+
+  // Verify spec file naming matches the primary target
+  if (!specFile.endsWith(".spec.ts")) {
+    errors.push({
+      type: "spec-name-mismatch",
+      message: `Spec file "${specFile}" must end with .spec.ts`,
+    });
+  } else {
+    const baseName = basename(specFile, ".spec.ts");
+    if (baseName !== target) {
+      errors.push({
+        type: "spec-name-mismatch",
+        message: `Spec file "${specFile}" doesn't match target "${target}". Expected "${target}.spec.ts".`,
+      });
+    }
+  }
+
+  // maxRules check
+  const ruleCount = Object.keys(spec.rules).length;
+  if (options.maxRules && ruleCount > options.maxRules) {
+    errors.push({
+      type: "invalid-rule",
+      message: `${String(ruleCount)} rules exceeds maxRules limit of ${String(options.maxRules)}. Split into subdirectory specs.`,
+    });
+  }
+
+  // Per-spec maxSectionLines takes precedence, then compile options
+  const maxSectionLines = spec.maxSectionLines ?? options.maxSectionLines;
+  const prose = compileSectionsSection(spec, basePath, maxSectionLines);
+  const keyFiles = compileKeyFilesSection(spec, basePath);
+  const commands = compileCommandsSection(spec, basePath);
+  const rules = compileRulesSection(spec, basePath, options);
+
+  sections.push(
+    ...prose.lines,
+    ...keyFiles.lines,
+    ...commands.lines,
+    ...rules.lines,
+  );
+  errors.push(
+    ...prose.errors,
+    ...keyFiles.errors,
+    ...commands.errors,
+    ...rules.errors,
+  );
+
+  const body = sections.join("\n\n") + "\n";
+  const tokens = estimateTokens(body);
+
+  // Per-spec maxTokens takes precedence, then compile options
+  const maxTokens = spec.maxTokens ?? options.maxTokens;
+  if (maxTokens && tokens > maxTokens) {
+    errors.push({
+      type: "budget-exceeded",
+      message: `Compiled output is ~${String(tokens)} tokens, exceeding maxTokens limit of ${String(maxTokens)}. Trim prose sections, split into multiple specs, or raise maxTokens.`,
+    });
+  }
+
+  const markdown = addHash(body, specFile);
+  const allTargets = Array.isArray(targets) ? targets : [targets];
+  return {
+    markdown,
+    errors,
+    linterResults: rules.linterResults,
+    tokens,
+    targets: allTargets,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Compile SKILL.md spec → markdown
+// ---------------------------------------------------------------------------
+
+function renderBody(body: string | InstructionFragment[]): string {
+  if (typeof body === "string") return body;
+  return body.map(renderFragment).join("");
+}
+
+export interface CompileSkillResult {
+  markdown: string;
+  errors: CompileError[];
+}
+
+/**
+ * Compile a SkillSpec into SKILL.md markdown with YAML frontmatter.
+ */
+export function compileSkill(
+  spec: SkillSpec,
+  options: { basePath?: string; specFile?: string } = {},
+): CompileSkillResult {
+  const basePath = options.basePath ?? process.cwd();
+  const specFile = options.specFile ?? "SKILL.md.spec.ts";
+  const errors: CompileError[] = [];
+
+  // Verify spec file naming
+  if (!specFile.endsWith(".spec.ts")) {
+    errors.push({
+      type: "spec-name-mismatch",
+      message: `Spec file "${specFile}" must end with .spec.ts`,
+    });
+  } else {
+    const baseName = basename(specFile, ".spec.ts");
+    if (!/\.md$/i.test(baseName)) {
+      errors.push({
+        type: "spec-name-mismatch",
+        message: `Spec file "${specFile}" should be named <output>.spec.ts (e.g., SKILL.md.spec.ts)`,
+      });
+    }
+  }
+
+  // Validate refs in body
+  if (Array.isArray(spec.body)) {
+    errors.push(...validateRefs(spec.body, basePath));
+  }
+
+  // Build frontmatter (blank lines after opening/before closing --- for prettier)
+  const fm: string[] = ["---", ""];
+  fm.push(`name: ${spec.name}`);
+  fm.push(`description: ${spec.description}`);
+  if (spec.disableModelInvocation !== undefined) {
+    fm.push(`disable-model-invocation: ${String(spec.disableModelInvocation)}`);
+  }
+  if (spec.argumentHint) {
+    fm.push(`argument-hint: ${spec.argumentHint}`);
+  }
+  fm.push("", "---");
+
+  const body = renderBody(spec.body);
+  const content = fm.join("\n") + "\n\n" + body.trim() + "\n";
+  const markdown = addHash(content, specFile);
+
+  return { markdown, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Hash check for existing files
+// ---------------------------------------------------------------------------
+
+export interface HashCheckResult {
+  hasHash: boolean;
+  valid: boolean;
+  specFile: string | null;
+}
+
+/** Check if a generated file's hash is intact. */
+export function checkFileHash(filePath: string): HashCheckResult {
+  if (!existsSync(filePath)) {
+    return { hasHash: false, valid: false, specFile: null };
+  }
+  const content = readFileSync(filePath, "utf-8");
+  const result = verifyHash(content);
+  if (!result) {
+    return { hasHash: false, valid: false, specFile: null };
+  }
+  return { hasHash: true, valid: result.valid, specFile: result.specFile };
+}
+
+// ---------------------------------------------------------------------------
+// Adopt: detect manual edits and show diff
+// ---------------------------------------------------------------------------
+
+export interface AdoptResult {
+  filePath: string;
+  hasHash: boolean;
+  valid: boolean;
+  specFile: string | null;
+  currentContent: string;
+  compiledContent: string | null;
+  addedLines: string[];
+  removedLines: string[];
+  changed: boolean;
+}
+
+/**
+ * Compare a generated file against what the spec would produce.
+ * Returns the diff so users can see what was manually changed.
+ */
+export function adoptDiff(
+  filePath: string,
+  spec: ClaudeSpec | SkillSpec,
+  basePath: string,
+): AdoptResult {
+  const fullPath = resolve(basePath, filePath);
+  const currentContent = existsSync(fullPath)
+    ? readFileSync(fullPath, "utf-8")
+    : "";
+
+  const hashResult = verifyHash(currentContent);
+
+  // Compile the spec to get what it WOULD produce
+  let compiledContent: string | null = null;
+  if (spec._specType === "claude") {
+    const { markdown } = compileClaude(spec, { basePath, specFile: filePath });
+    compiledContent = markdown;
+  } else if (spec._specType === "skill") {
+    const { markdown } = compileSkill(spec, { basePath, specFile: filePath });
+    compiledContent = markdown;
+  }
+
+  // Simple line-based diff
+  const currentLines = currentContent.replace(HASH_RE, "").split("\n");
+  const compiledLines = (compiledContent ?? "")
+    .replace(HASH_RE, "")
+    .split("\n");
+
+  const currentSet = new Set(currentLines);
+  const compiledSet = new Set(compiledLines);
+
+  const addedLines = currentLines.filter(
+    (l) => l.trim() && !compiledSet.has(l),
+  );
+  const removedLines = compiledLines.filter(
+    (l) => l.trim() && !currentSet.has(l),
+  );
+
+  return {
+    filePath,
+    hasHash: hashResult !== null,
+    valid: hashResult?.valid ?? false,
+    specFile: hashResult?.specFile ?? null,
+    currentContent,
+    compiledContent,
+    addedLines,
+    removedLines,
+    changed: addedLines.length > 0 || removedLines.length > 0,
+  };
+}