@minhpnq1807/contextos 0.1.0

package/plugins/ctx/lib/measure.js

@@ -0,0 +1,263 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { tokenize } from "./analyzer.js";
+
+const COMPLIANCE_STOPWORDS = new Set([
+  "always",
+  "before",
+  "cannot",
+  "cheaper",
+  "context",
+  "coverage",
+  "dependents",
+  "faster",
+  "fewer",
+  "gives",
+  "important",
+  "instead",
+  "never",
+  "project",
+  "rules",
+  "scanning",
+  "strictly",
+  "structural",
+  "that",
+  "this",
+  "tools",
+  "use",
+  "using",
+  "visible"
+]);
+
+const RUNTIME_EVIDENCE_PATTERNS = [
+  /\bbefore\s+(using|reading|grep|glob|read|searching)/i,
+  /\bafter\s+(running|checking|reading)/i,
+  /\balways\s+use\s+(code-review-graph|mcp|memory|agentmemory)\b/i,
+  /\bmust\s+run\b/i,
+  /\bdo not\s+prefix\b/i,
+  /\bkhong\s+the\b/i
+];
+
+const TEXT_EXTENSIONS = new Set([
+  ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".json", ".md", ".txt", ".yml", ".yaml", ".sql", ".py", ".sh", ".css", ".scss", ".html"
+]);
+const MAX_STATUS_FILE_LINES = 400;
+const MAX_STATUS_FILE_BYTES = 200_000;
+
+export function readGitSnapshot({ cwd = process.cwd() } = {}) {
+  try {
+    const diff = execFileSync("git", ["diff", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 1000
+    });
+    return parseGitDiff(diff);
+  } catch {
+    try {
+      const status = execFileSync("git", ["status", "--short"], {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 1000
+      });
+      const changedFiles = parseStatusFiles(status);
+      return {
+        mode: "status",
+        changedFiles,
+        addedLines: collectStatusAddedLines({ cwd, changedFiles }),
+        warnings: ["git diff HEAD unavailable; used git status and readable file content"]
+      };
+    } catch {
+      return {
+        mode: "none",
+        changedFiles: [],
+        addedLines: [],
+        warnings: ["git unavailable; skipped ContextOS measurement"]
+      };
+    }
+  }
+}
+
+function parseStatusFiles(status) {
+  return String(status || "")
+    .split(/\r?\n/)
+    .map((line) => line.slice(3).trim())
+    .filter(Boolean)
+    .map((file) => file.includes(" -> ") ? file.split(" -> ").at(-1).trim() : file);
+}
+
+function collectStatusAddedLines({ cwd, changedFiles }) {
+  const addedLines = [];
+  for (const file of changedFiles) {
+    if (addedLines.length >= MAX_STATUS_FILE_LINES) break;
+    if (!isReadableTextFile(file)) continue;
+    const fullPath = path.join(cwd, file);
+    let stat;
+    try {
+      stat = fs.statSync(fullPath);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile() || stat.size > MAX_STATUS_FILE_BYTES) continue;
+    let content = "";
+    try {
+      content = fs.readFileSync(fullPath, "utf8");
+    } catch {
+      continue;
+    }
+    const lines = content.split(/\r?\n/).slice(0, MAX_STATUS_FILE_LINES - addedLines.length);
+    lines.forEach((line, index) => {
+      if (line.trim()) addedLines.push({ file, line: index + 1, content: line });
+    });
+  }
+  return addedLines;
+}
+
+function isReadableTextFile(file) {
+  const base = path.basename(file);
+  if (base === "AGENTS.md" || base === "README.md" || base === "package.json") return true;
+  return TEXT_EXTENSIONS.has(path.extname(file));
+}
+
+export function parseGitDiff(diff) {
+  const changedFiles = new Set();
+  const addedLines = [];
+  let currentFile = null;
+  let newLine = null;
+
+  for (const line of String(diff || "").split(/\r?\n/)) {
+    const fileMatch = line.match(/^\+\+\+ b\/(.+)$/);
+    if (fileMatch) {
+      currentFile = fileMatch[1];
+      changedFiles.add(currentFile);
+      continue;
+    }
+    const hunkMatch = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hunkMatch) {
+      newLine = Number(hunkMatch[1]);
+      continue;
+    }
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      addedLines.push({ file: currentFile, line: newLine, content: line.slice(1) });
+      if (typeof newLine === "number") newLine += 1;
+    } else if (!line.startsWith("-") && typeof newLine === "number") {
+      newLine += 1;
+    }
+  }
+
+  return {
+    mode: "diff",
+    changedFiles: [...changedFiles],
+    addedLines,
+    warnings: []
+  };
+}
+
+export function checkCompliance({ rules = [], addedLines = [] } = {}) {
+  const results = [];
+
+  for (const rule of rules) {
+    const lower = rule.content.toLowerCase();
+    const keywords = extractComplianceKeywords(rule.content);
+    const isRuntimeOnly = needsRuntimeEvidence(rule.content);
+    const kind = lower.includes("no ") || lower.includes("never") || lower.includes("khong")
+      ? "forbidden"
+      : "required";
+
+    if (!keywords.length || !addedLines.length) {
+      results.push({
+        rule,
+        status: "unknown",
+        kind,
+        keywords,
+        evidence: !addedLines.length ? "no added lines in git diff" : "no concrete compliance keywords found"
+      });
+      continue;
+    }
+
+    if (isRuntimeOnly) {
+      results.push({
+        rule,
+        status: "unknown",
+        kind: "runtime",
+        keywords,
+        evidence: "requires runtime/tool-call evidence, not git diff evidence"
+      });
+      continue;
+    }
+
+    if (kind === "forbidden") {
+      const violation = findKeywordEvidence(addedLines, keywords);
+      const violated = violation?.keyword;
+      results.push(violated
+        ? {
+          rule,
+          status: "ignored",
+          kind,
+          keywords,
+          evidence: `found forbidden ${violated} in ${formatLineRef(violation.line)}`,
+          matchedLines: [violation.line]
+        }
+        : {
+          rule,
+          status: "followed",
+          kind,
+          keywords,
+          evidence: `forbidden keywords not found: ${keywords.join(", ")}`
+        });
+      continue;
+    }
+
+    const match = findKeywordEvidence(addedLines, keywords);
+    const matched = match?.keyword;
+    results.push(matched
+      ? {
+        rule,
+        status: "followed",
+        kind,
+        keywords,
+        evidence: `found required ${matched} in ${formatLineRef(match.line)}`,
+        matchedLines: [match.line]
+      }
+      : {
+        rule,
+        status: "unknown",
+        kind,
+        keywords,
+        evidence: `expected keywords not visible in added lines: ${keywords.join(", ")}`
+      });
+  }
+
+  return results;
+}
+
+function needsRuntimeEvidence(content) {
+  return RUNTIME_EVIDENCE_PATTERNS.some((pattern) => pattern.test(content));
+}
+
+function findKeywordEvidence(lines, keywords) {
+  for (const keyword of keywords) {
+    const normalized = keyword.toLowerCase();
+    const line = lines.find((item) => String(item.content || "").toLowerCase().includes(normalized));
+    if (line) return { keyword, line };
+  }
+  return null;
+}
+
+function formatLineRef(line) {
+  if (!line?.file) return "diff";
+  return typeof line.line === "number" ? `${line.file}:${line.line}` : line.file;
+}
+
+function extractComplianceKeywords(content) {
+  const explicit = [...String(content || "").matchAll(/`([^`]+)`/g)].map((match) => match[1]);
+  const tokens = tokenize(content).filter((token) => {
+    if (token.length < 3) return false;
+    if (COMPLIANCE_STOPWORDS.has(token)) return false;
+    return /[./_-]/.test(token) || /^[a-z][a-z0-9]*$/i.test(token);
+  });
+  return [...new Set([...explicit, ...tokens])].slice(0, 8);
+}

package/plugins/ctx/lib/prompt-hook.js

@@ -0,0 +1,72 @@
+import { scheduleContext } from "./scheduler.js";
+import { appendJsonLine, writeJsonFile } from "./fs-utils.js";
+import { callCtxScoreContext } from "./ctx-mcp-client.js";
+import path from "node:path";
+
+export async function handlePromptPayload(
+  payload,
+  {
+    dataPath,
+    historyPath,
+    now = new Date(),
+    started = Date.now(),
+    injectContext = process.env.CONTEXTOS_INJECT !== "0",
+    scoreContextClient = callCtxScoreContext
+  } = {}
+) {
+  const prompt = payload.prompt || payload.message || payload.user_prompt || "";
+  const cwd = payload.cwd || payload.working_directory || process.cwd();
+  const openFiles = payload.openFiles || payload.open_files || payload.files || [];
+  const dataDir = dataPath ? path.dirname(dataPath) : undefined;
+
+  const scored = await scoreContextClient({
+    cwd,
+    prompt,
+    openFiles,
+    maxFiles: 3
+  }, {
+    dataDir,
+    timeoutMs: Number(process.env.CONTEXTOS_MCP_BRIDGE_TIMEOUT_MS || 1000)
+  });
+
+  if (scored.error) throw new Error(scored.error);
+  const scoredRules = scored.scoredRules || [];
+  const relevantFiles = (scored.suggestedFiles || []).slice(0, 3);
+  const scheduled = scheduleContext({ rules: scoredRules, relevantFiles });
+
+  const runtime = {
+    at: now.toISOString(),
+    cwd,
+    prompt,
+    rules: scoredRules,
+    scoring: {
+      keyword: true,
+      mcp: scored.telemetry || {}
+    },
+    relevantFiles,
+    telemetry: {
+      ...(scored.telemetry || {}),
+      rulesInjected: (scheduled.highRules?.length || 0) + (scheduled.midRules?.length || 0),
+      filesSuggested: relevantFiles.length
+    },
+    scheduled,
+    injected: injectContext,
+    elapsedMs: Date.now() - started
+  };
+
+  try {
+    if (dataPath) writeJsonFile(dataPath, runtime);
+    if (historyPath) appendJsonLine(historyPath, runtime);
+  } catch {
+    // Context injection is the critical path; diagnostics are best-effort.
+  }
+
+  return {
+    continue: true,
+    suppressOutput: true,
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: injectContext ? scheduled.additionalContext : ""
+    }
+  };
+}

package/plugins/ctx/lib/reader.js

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { safeReadText } from "./fs-utils.js";
+
+function findProjectRoot(cwd) {
+  let current = path.resolve(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(cwd);
+    current = parent;
+  }
+}
+
+function pathChain(root, cwd) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedCwd = path.resolve(cwd);
+  const relative = path.relative(resolvedRoot, resolvedCwd);
+  const parts = relative && !relative.startsWith("..") ? relative.split(path.sep) : [];
+  const chain = [resolvedRoot];
+  let current = resolvedRoot;
+  for (const part of parts) {
+    current = path.join(current, part);
+    chain.push(current);
+  }
+  return chain;
+}
+
+export function readAgentsChain({ cwd = process.cwd(), home = process.env.HOME } = {}) {
+  const files = [];
+  if (home) files.push(path.join(home, ".codex", "AGENTS.md"));
+
+  const root = findProjectRoot(cwd);
+  for (const directory of pathChain(root, cwd)) {
+    files.push(path.join(directory, "AGENTS.md"));
+  }
+
+  const sources = [];
+  const sections = [];
+  const seen = new Set();
+
+  for (const filePath of files) {
+    if (seen.has(filePath) || !fs.existsSync(filePath)) continue;
+    seen.add(filePath);
+    const content = safeReadText(filePath).trim();
+    if (!content) continue;
+    sources.push(filePath);
+    sections.push(`## Source: ${filePath}\n${content}`);
+  }
+
+  return {
+    root,
+    sources,
+    content: sections.join("\n\n")
+  };
+}

package/plugins/ctx/lib/reporter.js

@@ -0,0 +1,105 @@
+export function buildReport({ cwd, prompt, relevantFiles, scheduled, gitSnapshot, compliance }) {
+  const followed = compliance.filter((item) => item.status === "followed");
+  const ignored = compliance.filter((item) => item.status === "ignored");
+  const unknown = compliance.filter((item) => item.status === "unknown");
+  const measured = followed.length + ignored.length;
+  const efficiencyScore = measured ? Math.round((followed.length / measured) * 100) : null;
+
+  return {
+    at: new Date().toISOString(),
+    cwd,
+    prompt,
+    injectedRuleCount: (scheduled?.highRules?.length || 0) + (scheduled?.midRules?.length || 0),
+    relevantFiles,
+    changedFiles: gitSnapshot.changedFiles,
+    warnings: gitSnapshot.warnings || [],
+    followed,
+    ignored,
+    unknown,
+    measuredRuleCount: measured,
+    unknownRuleCount: unknown.length,
+    efficiencyScore
+  };
+}
+
+export function formatReport(report) {
+  const lines = [];
+  lines.push("ContextOS report");
+  lines.push(`Efficiency: ${report.efficiencyScore == null ? "unknown" : `${report.efficiencyScore}%`}`);
+  lines.push(`Injected rules: ${report.injectedRuleCount || 0}`);
+  lines.push(`Rule outcomes: ${report.followed?.length || 0} followed, ${report.ignored?.length || 0} ignored, ${report.unknown?.length || 0} unknown`);
+  lines.push(`Measured rules: ${report.measuredRuleCount ?? ((report.followed?.length || 0) + (report.ignored?.length || 0))}`);
+  lines.push(`Changed files: ${report.changedFiles?.length ? report.changedFiles.join(", ") : "none detected"}`);
+
+  if (report.relevantFiles?.length) {
+    lines.push(`Suggested files: ${report.relevantFiles.map((file) => file.path).join(", ")}`);
+  }
+
+  for (const warning of report.warnings || []) lines.push(`Warning: ${warning}`);
+
+  appendBucket(lines, "Followed", report.followed);
+  appendBucket(lines, "Ignored", report.ignored);
+  appendBucket(lines, "Unknown", report.unknown);
+
+  if (report.ignored?.length) {
+    lines.push(`Suggestion: fix ignored rule evidence first: ${truncate(report.ignored[0].rule?.content || "", 70)}`);
+  } else if (report.unknown?.length && !(report.followed?.length || report.ignored?.length)) {
+    lines.push("Suggestion: these rules need runtime evidence or more concrete keywords before ContextOS can score them from git diff.");
+  }
+
+  return lines.join("\n");
+}
+
+export function formatEvidence(report) {
+  const lines = [];
+  lines.push("ContextOS evidence");
+  lines.push(`Prompt: ${report.prompt || "(empty)"}`);
+  lines.push(`Efficiency: ${report.efficiencyScore == null ? "unknown" : `${report.efficiencyScore}%`}`);
+  lines.push(`Changed files: ${report.changedFiles?.length ? report.changedFiles.join(", ") : "none detected"}`);
+
+  for (const warning of report.warnings || []) lines.push(`Warning: ${warning}`);
+
+  const items = [
+    ...(report.followed || []).map((item) => ({ ...item, status: "followed" })),
+    ...(report.ignored || []).map((item) => ({ ...item, status: "ignored" })),
+    ...(report.unknown || []).map((item) => ({ ...item, status: "unknown" }))
+  ];
+
+  if (!items.length) {
+    lines.push("No rule evidence captured for the last report.");
+    lines.push("Run a task that schedules at least one relevant rule, then let the Stop hook finish.");
+    return lines.join("\n");
+  }
+
+  items.forEach((item, index) => {
+    lines.push("");
+    lines.push(`${index + 1}. ${item.status.toUpperCase()}`);
+    lines.push(`Rule: ${item.rule?.content || "(missing rule)"}`);
+    if (item.rule?.sourcePath) lines.push(`Source: ${item.rule.sourcePath}`);
+    if (typeof item.rule?.score === "number") lines.push(`Score: ${item.rule.score.toFixed(2)}`);
+    if (item.kind) lines.push(`Kind: ${item.kind}`);
+    if (item.keywords?.length) lines.push(`Keywords: ${item.keywords.join(", ")}`);
+    lines.push(`Evidence: ${item.evidence || "(none)"}`);
+    for (const line of item.matchedLines || []) {
+      const where = line.file ? `${line.file}${typeof line.line === "number" ? `:${line.line}` : ""}` : "diff";
+      lines.push(`Matched line: ${where} ${truncate(line.content || "", 140)}`);
+    }
+  });
+
+  return lines.join("\n");
+}
+
+function appendBucket(lines, label, items = []) {
+  if (!items.length) return;
+  lines.push(`${label}:`);
+  for (const item of items.slice(0, 5)) {
+    lines.push(`- Rule: ${truncate(item.rule.content, 68)}`);
+    lines.push(`  Evidence: ${truncate(item.evidence, 64)}`);
+  }
+  if (items.length > 5) lines.push(`- ... ${items.length - 5} more`);
+}
+
+function truncate(value, max) {
+  const normalized = String(value || "").replace(/\s+/g, " ").trim();
+  return normalized.length > max ? `${normalized.slice(0, max - 3)}...` : normalized;
+}

package/plugins/ctx/lib/scheduler.js

@@ -0,0 +1,45 @@
+const MAX_CONTEXT_CHARS = 4000;
+
+export function scheduleContext({ rules = [], relevantFiles = [], maxChars = MAX_CONTEXT_CHARS } = {}) {
+  const high = rules.filter((rule) => rule.score >= 0.5);
+  const mid = rules.filter((rule) => rule.score >= 0.1 && rule.score < 0.5);
+  const dropped = rules.filter((rule) => rule.score < 0.1);
+
+  const sections = [];
+  if (high.length) {
+    sections.push(section("Critical ContextOS rules", high.slice(0, 8).map(formatRule)));
+  }
+  if (relevantFiles.length) {
+    sections.push(section("Suggested files to check", relevantFiles.map((file) => `- ${file.path}`)));
+  }
+  if (mid.length) {
+    sections.push(section("Additional relevant rules", mid.slice(0, 8).map(formatRule)));
+  }
+  if (high.length) {
+    sections.push(section("ContextOS reminders", high.slice(0, 5).map(formatRule)));
+  }
+
+  const additionalContext = trimToLimit(sections.filter(Boolean).join("\n\n"), maxChars);
+  return {
+    highRules: high,
+    midRules: mid,
+    droppedRules: dropped,
+    relevantFiles,
+    additionalContext
+  };
+}
+
+function section(title, lines) {
+  if (!lines.length) return "";
+  return `## ${title}\n${lines.join("\n")}`;
+}
+
+function formatRule(rule) {
+  const source = rule.sourcePath && rule.sourcePath !== "unknown" ? ` (${rule.sourcePath})` : "";
+  return `- ${rule.content}${source}`;
+}
+
+function trimToLimit(value, maxChars) {
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, Math.max(0, maxChars - 80)).trimEnd()}\n\n[ContextOS truncated context to ${maxChars} chars]`;
+}

package/plugins/ctx/lib/score-context.js

@@ -0,0 +1,55 @@
+import path from "node:path";
+
+import { readAgentsChain } from "./reader.js";
+import { parseRules, scoreRules, findRelevantFiles } from "./analyzer.js";
+import { enhanceRuleScoresWithEmbeddings } from "./embedding-scorer.js";
+
+export async function scoreContext({
+  cwd = process.cwd(),
+  prompt = "",
+  openFiles = [],
+  dataDir,
+  maxFiles = 5,
+  embeddingTimeoutMs = 5000,
+  fileEmbeddingTimeoutMs = Number(process.env.CONTEXTOS_FILE_EMBEDDING_TIMEOUT_MS || 80)
+} = {}) {
+  const started = Date.now();
+  const merged = readAgentsChain({ cwd });
+  const parsedRules = parseRules(merged.content);
+  const baseScoredRules = scoreRules(parsedRules, prompt, openFiles);
+  const embedding = await enhanceRuleScoresWithEmbeddings(baseScoredRules, prompt, {
+    dataDir,
+    sources: merged.sources,
+    timeoutMs: embeddingTimeoutMs,
+    allowRemote: false
+  });
+  const scoredRules = embedding.rules;
+  const suggestedFiles = await findRelevantFiles({
+    cwd,
+    task: prompt,
+    rules: scoredRules,
+    dataDir,
+    limit: maxFiles,
+    fileEmbeddingTimeoutMs,
+    fileEmbeddingOptions: {
+      allowRemote: false
+    }
+  });
+
+  return {
+    cwd,
+    prompt,
+    scoredRules,
+    suggestedFiles,
+    telemetry: {
+      elapsedMs: Date.now() - started,
+      modelStatus: embedding.status,
+      model: embedding.model,
+      cachePath: embedding.cachePath,
+      rulesParsed: parsedRules.length,
+      rulesInjected: scoredRules.filter((rule) => Number(rule.score || 0) >= 0.1).length,
+      filesSuggested: suggestedFiles.length,
+      sources: merged.sources.map((source) => path.relative(cwd, source))
+    }
+  };
+}