@orangepro/orangepro-mcp 0.1.0

package/dist/local/cliArgs.js

@@ -0,0 +1,112 @@
+/**
+ * CLI argument parsing for the OrangePro Local Proof Kit.
+ *
+ * Extracted from cli.ts so it can be unit-tested without importing the CLI
+ * entrypoint (cli.ts runs main() at module load).
+ */
+/**
+ * Flags that consume the FOLLOWING token as their value (e.g. `--limit 10`).
+ * Every other `--flag` is treated as a value-less boolean, so a trailing
+ * positional after a boolean flag (e.g. `opro start --no-ai server/public`)
+ * is preserved as a positional rather than swallowed as the flag's value.
+ */
+export const VALUE_FLAGS = new Set([
+    "agent-pass",
+    "auto-limit",
+    "base",
+    "client",
+    "coverage-timeout-ms",
+    "entity",
+    "evidence-ids",
+    "format",
+    "framework",
+    "include-markdown",
+    "job-id",
+    "limit",
+    "jest-config",
+    "max-behaviors",
+    "max-prompt-tokens",
+    "method",
+    "min-priority",
+    "model",
+    "out",
+    "paths",
+    "pr",
+    "prompt-version",
+    "provider",
+    "replacement",
+    "replacement-mode",
+    "runner",
+    "run-id",
+    "seed-field",
+    "setup",
+    "setup-timeout-ms",
+    "source",
+    "status",
+    "symbols-per-behavior",
+    "target",
+    "target-file",
+    "target-symbol",
+    "test",
+    "test-env",
+    "vitest-config",
+    "timeout-ms"
+]);
+export function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith("--")) {
+            const key = token.slice(2);
+            const next = argv[i + 1];
+            if (VALUE_FLAGS.has(key) && next !== undefined && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    return { positionals, flags };
+}
+/**
+ * Split a `--setup "cmd arg arg"` value into an argv, respecting single/double
+ * quotes so a space-bearing arg (e.g. `--schema "a b.prisma"` or `--schema="a b"`)
+ * stays one token.
+ *
+ * ponytail: not a full shell parser — no backslash escapes, env expansion, or
+ * unbalanced-quote recovery. For exotic args use the MCP structured setup_commands.
+ */
+export function tokenizeSetup(value) {
+    const tokens = [];
+    const re = /(?:[^\s"']+|"[^"]*"|'[^']*')+/g;
+    for (const raw of value.match(re) ?? []) {
+        tokens.push(raw.replace(/"([^"]*)"|'([^']*)'/g, (_, dq, sq) => dq ?? sq));
+    }
+    return tokens;
+}
+/**
+ * Collect repeatable `--setup "cmd arg arg"` flags into setup commands. Scans the
+ * raw arg list (parseArgs collapses repeated flags to the last value), tokenizing
+ * each value quote-aware into { command, args }.
+ */
+export function collectSetupCommands(rest) {
+    const commands = [];
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] !== "--setup")
+            continue;
+        const value = rest[i + 1];
+        if (typeof value !== "string" || value.startsWith("--"))
+            continue;
+        const [command, ...args] = tokenizeSetup(value);
+        if (command)
+            commands.push({ command, args });
+        i++;
+    }
+    return commands;
+}

package/dist/local/corpusScope.js

@@ -0,0 +1,162 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULT_LARGE_FILE_THRESHOLD = 2_000;
+const DEFAULT_LARGE_SCOPE_THRESHOLD = 1_000;
+const MAX_VISITED_FILES = 100_000;
+const SKIP_DIRS = new Set([
+    ".cache",
+    ".git",
+    ".next",
+    ".orangepro",
+    ".serena",
+    ".turbo",
+    ".venv",
+    "__pycache__",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "target",
+    "vendor",
+    "venv"
+]);
+const INCLUDED_EXTENSIONS = new Set([
+    ".c",
+    ".cc",
+    ".cpp",
+    ".cs",
+    ".css",
+    ".go",
+    ".h",
+    ".hpp",
+    ".java",
+    ".js",
+    ".jsx",
+    ".kt",
+    ".md",
+    ".mdx",
+    ".php",
+    ".py",
+    ".rb",
+    ".rs",
+    ".swift",
+    ".ts",
+    ".tsx",
+    ".txt",
+    ".vue"
+]);
+const INCLUDED_FILENAMES = new Set([
+    "dockerfile",
+    "gemfile",
+    "go.mod",
+    "package.json",
+    "pom.xml",
+    "requirements.txt"
+]);
+function extensionOf(name) {
+    const idx = name.lastIndexOf(".");
+    return idx >= 0 ? name.slice(idx).toLowerCase() : "";
+}
+function isIncludedFile(name) {
+    const lower = name.toLowerCase();
+    return INCLUDED_FILENAMES.has(lower) || INCLUDED_EXTENSIONS.has(extensionOf(lower));
+}
+function increment(map, key) {
+    map.set(key, (map.get(key) ?? 0) + 1);
+}
+function noteFor(files, largeScopeThreshold) {
+    if (files >= largeScopeThreshold)
+        return "still large — consider one level deeper";
+    if (files >= Math.ceil(largeScopeThreshold / 2))
+        return "medium scope — usable, but narrower is cheaper";
+    return "small enough to graph directly";
+}
+function topEntries(topCounts, childCounts, total, largeScopeThreshold) {
+    return [...topCounts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([path, files]) => ({
+        path,
+        files,
+        share_pct: total > 0 ? Math.round((files / total) * 1000) / 10 : 0,
+        note: noteFor(files, largeScopeThreshold),
+        children: [...(childCounts.get(path)?.entries() ?? [])]
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+            .slice(0, 4)
+            .map(([child, childFiles]) => ({ path: child, files: childFiles }))
+    }));
+}
+export function summarizeCorpusScope(root, opts = {}) {
+    const largeFileThreshold = opts.largeFileThreshold ?? DEFAULT_LARGE_FILE_THRESHOLD;
+    const largeScopeThreshold = opts.largeScopeThreshold ?? DEFAULT_LARGE_SCOPE_THRESHOLD;
+    const maxVisitedFiles = opts.maxVisitedFiles ?? MAX_VISITED_FILES;
+    const topCounts = new Map();
+    const childCounts = new Map();
+    let files = 0;
+    let visited = 0;
+    let truncated = false;
+    const visit = (relDir) => {
+        if (truncated)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(join(root, relDir), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (truncated)
+                return;
+            if (entry.name.startsWith("."))
+                continue;
+            const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                visit(rel);
+                continue;
+            }
+            if (!entry.isFile() || !isIncludedFile(entry.name))
+                continue;
+            visited++;
+            if (visited > maxVisitedFiles) {
+                truncated = true;
+                return;
+            }
+            files++;
+            const parts = rel.split("/");
+            if (parts.length === 1)
+                continue;
+            const top = parts[0] || ".";
+            increment(topCounts, top);
+            if (parts.length > 2) {
+                const child = `${top}/${parts[1]}`;
+                const children = childCounts.get(top) ?? new Map();
+                increment(children, child);
+                childCounts.set(top, children);
+            }
+        }
+    };
+    visit("");
+    const top = topEntries(topCounts, childCounts, files, largeScopeThreshold);
+    const isLarge = files >= largeFileThreshold || top.some((entry) => entry.files >= largeScopeThreshold);
+    return {
+        root,
+        files,
+        truncated,
+        is_large: isLarge,
+        thresholds: {
+            large_files: largeFileThreshold,
+            large_scope_files: largeScopeThreshold
+        },
+        top_level: top.slice(0, 8),
+        suggested_scopes: top.slice(0, 5),
+        guidance: isLarge
+            ? [
+                "OrangePro can still build the deterministic graph locally.",
+                "For faster AI grounding and cleaner agent work, start from a focused subdirectory or PR diff.",
+                "If a suggested scope is still large, use one of its child directories."
+            ]
+            : ["This scope is small enough for a direct OrangePro run."]
+    };
+}

package/dist/local/enrich/csv.js

@@ -0,0 +1,348 @@
+import { makeCandidateEdge, makeEdge, makeNode } from "../graph/factories.js";
+import { hashString } from "../util/hash.js";
+import { slugify } from "../util/ids.js";
+import { redactSecrets } from "../util/redact.js";
+const DETECTOR = "csv_template";
+/** Aliases mapping normalized header tokens onto canonical column keys. */
+const HEADER_ALIASES = {
+    behavior_name: "behavior_name",
+    behavior: "behavior_name",
+    behaviour_name: "behavior_name",
+    name: "behavior_name",
+    description: "description",
+    desc: "description",
+    acceptance_criteria: "acceptance_criteria",
+    acceptance: "acceptance_criteria",
+    ac: "acceptance_criteria",
+    actor_or_role: "actor_or_role",
+    actor: "actor_or_role",
+    role: "actor_or_role",
+    actors: "actor_or_role",
+    priority_or_risk: "priority_or_risk",
+    priority: "priority_or_risk",
+    risk: "priority_or_risk",
+    source_ref: "source_ref",
+    source: "source_ref",
+    source_reference: "source_ref",
+    workflow_steps: "workflow_steps",
+    workflow: "workflow_steps",
+    steps: "workflow_steps",
+    screen_api_service_or_job: "screen_api_service_or_job",
+    screen_api_service_job: "screen_api_service_or_job",
+    interface: "screen_api_service_or_job",
+    known_edge_cases: "known_edge_cases",
+    edge_cases: "known_edge_cases",
+    known_bugs_or_incidents: "known_bugs_or_incidents",
+    known_bugs: "known_bugs_or_incidents",
+    bugs: "known_bugs_or_incidents",
+    incidents: "known_bugs_or_incidents",
+    manual_qa_steps: "manual_qa_steps",
+    manual_qa: "manual_qa_steps",
+    existing_test_names_or_links: "existing_test_names_or_links",
+    existing_tests: "existing_test_names_or_links",
+    existing_test_names: "existing_test_names_or_links",
+    related_jira_confluence_testrail_github_ids: "related_jira_confluence_testrail_github_ids",
+    related_ids: "related_jira_confluence_testrail_github_ids",
+    related: "related_jira_confluence_testrail_github_ids"
+};
+/** Header tokens (any one present) that mark a line as the template header row. */
+const HEADER_SIGNAL_TOKENS = new Set(["behavior_name", "behavior", "behaviour_name", "acceptance_criteria"]);
+/** Normalize a header cell to a comparable token (case/space/underscore-insensitive). */
+function normalizeHeader(cell) {
+    return cell
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+/**
+ * True when the given line plausibly is the OrangePro template header row.
+ * Used by the .txt routing fallback in the dispatcher.
+ */
+export function looksLikeTemplateHeader(line) {
+    const cells = parseCsv(line)[0] ?? [];
+    return cells.some((c) => HEADER_SIGNAL_TOKENS.has(normalizeHeader(c)));
+}
+/**
+ * Minimal RFC-4180-ish CSV parser. Handles quoted fields, commas/newlines inside
+ * quotes, escaped double-quotes (""), and CRLF. Returns rows of string cells.
+ */
+function parseCsv(content) {
+    const rows = [];
+    let row = [];
+    let field = "";
+    let inQuotes = false;
+    let i = 0;
+    const n = content.length;
+    const pushField = () => {
+        row.push(field);
+        field = "";
+    };
+    const pushRow = () => {
+        pushField();
+        rows.push(row);
+        row = [];
+    };
+    while (i < n) {
+        const ch = content[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                if (content[i + 1] === '"') {
+                    field += '"';
+                    i += 2;
+                    continue;
+                }
+                inQuotes = false;
+                i++;
+                continue;
+            }
+            field += ch;
+            i++;
+            continue;
+        }
+        if (ch === '"') {
+            inQuotes = true;
+            i++;
+            continue;
+        }
+        if (ch === ",") {
+            pushField();
+            i++;
+            continue;
+        }
+        if (ch === "\r") {
+            if (content[i + 1] === "\n")
+                i++;
+            pushRow();
+            i++;
+            continue;
+        }
+        if (ch === "\n") {
+            pushRow();
+            i++;
+            continue;
+        }
+        field += ch;
+        i++;
+    }
+    // Flush trailing field/row unless the content ended with a clean newline and no
+    // dangling data.
+    if (field.length > 0 || row.length > 0)
+        pushRow();
+    return rows;
+}
+/** Drop rows that are entirely empty (no non-whitespace cell). */
+function isBlankRow(cells) {
+    return cells.every((c) => c.trim() === "");
+}
+/** Split a multi-item cell on ';' or newlines; trims and drops empties. */
+function splitItems(value) {
+    return value
+        .split(/[;\n\r]+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/** Zero-padded requirement index (1 -> "001"). */
+function padIndex(n) {
+    return String(n).padStart(3, "0");
+}
+/**
+ * Enrich from the OrangePro minimum customer template (CSV).
+ *
+ * Reviewed template rows are treated as HARD evidence: each data row yields a
+ * Requirement node plus hard acceptance-criterion edges, candidate interface
+ * edges, and (where present) regression links from incidents. Privacy: only
+ * metadata is captured and any free text is run through secret redaction.
+ */
+export function enrichFromCsv(relPath, content) {
+    const nodes = [];
+    const edges = [];
+    const candidate_edges = [];
+    const warnings = [];
+    const sourceScopeId = "manual_template:" + slugify(relPath);
+    const source = {
+        source_scope_id: sourceScopeId,
+        source_system: "manual_template",
+        source_type: "customer_supplied",
+        display_name: relPath,
+        content_hash: hashString(content),
+        metadata: { filename: relPath }
+    };
+    const allRows = parseCsv(content).filter((r) => !isBlankRow(r));
+    if (allRows.length === 0) {
+        warnings.push(`CSV template '${relPath}' has no rows.`);
+        return { nodes, edges, candidate_edges, sources: [source], warnings };
+    }
+    const headerCells = allRows[0];
+    // Only treat a CSV as an OrangePro template if it carries a strong signal
+    // column. A bare data CSV (e.g. `id,name,qty`) must NOT become requirements.
+    const hasTemplateSignal = headerCells.some((c) => HEADER_SIGNAL_TOKENS.has(normalizeHeader(c)));
+    if (!hasTemplateSignal) {
+        return {
+            nodes: [],
+            edges: [],
+            candidate_edges: [],
+            sources: [],
+            warnings: [`CSV '${relPath}' is not an OrangePro template (no behavior_name/acceptance_criteria column); skipped.`]
+        };
+    }
+    const columnIndex = new Map();
+    for (let c = 0; c < headerCells.length; c++) {
+        const key = HEADER_ALIASES[normalizeHeader(headerCells[c])];
+        if (key && !columnIndex.has(key))
+            columnIndex.set(key, c);
+    }
+    if (!columnIndex.has("behavior_name")) {
+        warnings.push(`CSV template '${relPath}' is missing a recognizable 'behavior_name' column.`);
+    }
+    const cell = (row, key) => {
+        const idx = columnIndex.get(key);
+        if (idx === undefined)
+            return "";
+        const raw = row[idx];
+        return raw === undefined ? "" : redactSecrets(raw).trim();
+    };
+    const dataRows = allRows.slice(1);
+    let reqIndex = 0;
+    for (let r = 0; r < dataRows.length; r++) {
+        const row = dataRows[r];
+        const behaviorName = cell(row, "behavior_name");
+        if (behaviorName === "")
+            continue;
+        reqIndex++;
+        const rowNumber = r + 2; // 1-based, accounting for the header row.
+        const reqExternalId = "REQ-" + padIndex(reqIndex) + "-" + slugify(behaviorName);
+        const description = cell(row, "description");
+        const actorsRaw = cell(row, "actor_or_role");
+        const actors = splitItems(actorsRaw);
+        const priority = cell(row, "priority_or_risk");
+        const sourceRef = cell(row, "source_ref");
+        const workflowSteps = splitItems(cell(row, "workflow_steps"));
+        const screenApi = cell(row, "screen_api_service_or_job");
+        const knownEdgeCases = splitItems(cell(row, "known_edge_cases"));
+        const knownBugs = splitItems(cell(row, "known_bugs_or_incidents"));
+        const manualQaSteps = cell(row, "manual_qa_steps");
+        const existingTestNames = splitItems(cell(row, "existing_test_names_or_links"));
+        const relatedIds = cell(row, "related_jira_confluence_testrail_github_ids");
+        const acceptanceCriteria = splitItems(cell(row, "acceptance_criteria"));
+        const rowProvenance = {
+            source_scope_id: sourceScopeId,
+            source_ref: sourceRef || `${relPath}#row=${rowNumber}`,
+            detector: DETECTOR
+        };
+        const properties = {};
+        if (description)
+            properties.description = description;
+        if (acceptanceCriteria.length > 0)
+            properties.acceptance_criteria = acceptanceCriteria;
+        if (actors.length > 0)
+            properties.actors = actors;
+        if (priority)
+            properties.priority = priority;
+        if (workflowSteps.length > 0)
+            properties.workflow_steps = workflowSteps;
+        if (screenApi)
+            properties.screen_api_service_or_job = screenApi;
+        if (knownEdgeCases.length > 0)
+            properties.known_edge_cases = knownEdgeCases;
+        if (knownBugs.length > 0)
+            properties.known_bugs = knownBugs;
+        if (manualQaSteps)
+            properties.manual_qa_steps = manualQaSteps;
+        if (existingTestNames.length > 0)
+            properties.existing_test_names = existingTestNames;
+        if (relatedIds)
+            properties.related_ids = relatedIds;
+        nodes.push(makeNode({
+            kind: "Requirement",
+            external_id: reqExternalId,
+            title: behaviorName,
+            properties,
+            evidence_strength: "hard",
+            review_status: "local_reviewed",
+            confidence: 0.95,
+            provenance: rowProvenance,
+            content_hash: hashString(behaviorName + "|" + description),
+            behavior_source: "requirement_template",
+            denominator_eligible: true,
+            denominator_reason: "Reviewed template row — explicit behavior."
+        }));
+        // Acceptance criteria → hard AcceptanceCriterion nodes + HAS_ACCEPTANCE_CRITERION edges.
+        for (let a = 0; a < acceptanceCriteria.length; a++) {
+            const acText = acceptanceCriteria[a];
+            const acExternalId = "AC-" + slugify(behaviorName) + "-" + padIndex(a + 1);
+            nodes.push(makeNode({
+                kind: "AcceptanceCriterion",
+                external_id: acExternalId,
+                title: acText,
+                properties: { text: acText, behavior: reqExternalId },
+                evidence_strength: "hard",
+                review_status: "local_reviewed",
+                confidence: 0.95,
+                provenance: rowProvenance,
+                content_hash: hashString(acText)
+            }));
+            edges.push(makeEdge({
+                from_external_id: reqExternalId,
+                to_external_id: acExternalId,
+                relationship_type: "HAS_ACCEPTANCE_CRITERION",
+                evidence_strength: "hard",
+                review_status: "local_reviewed",
+                provenance: rowProvenance
+            }));
+        }
+        // Interface field → Service/Endpoint node + candidate MAY_REQUIRE_INTERFACE edge.
+        if (screenApi) {
+            const ifaceSlug = slugify(screenApi);
+            const ifaceExternalId = "iface:" + ifaceSlug;
+            const isEndpoint = /\/|https?:|\bapi\b|endpoint|route|\bget\b|\bpost\b|\bput\b|\bdelete\b/i.test(screenApi);
+            nodes.push(makeNode({
+                kind: isEndpoint ? "Endpoint" : "Service",
+                external_id: ifaceExternalId,
+                title: screenApi,
+                properties: { name: screenApi, inferred_from: "template_interface_field" },
+                evidence_strength: "candidate",
+                review_status: "inferred",
+                confidence: 0.6,
+                provenance: rowProvenance
+            }));
+            candidate_edges.push(makeCandidateEdge({
+                from_external_id: reqExternalId,
+                to_external_id: ifaceExternalId,
+                relationship_type: "MAY_REQUIRE_INTERFACE",
+                evidence_strength: "candidate",
+                reason: "from template interface field",
+                confidence: 0.6,
+                provenance: rowProvenance
+            }));
+        }
+        // Known bugs/incidents → Incident node + hard REGRESSION_OF edge (Incident → behavior).
+        for (let b = 0; b < knownBugs.length; b++) {
+            const bugText = knownBugs[b];
+            const incidentExternalId = "incident:" + slugify(behaviorName) + "-" + padIndex(b + 1);
+            nodes.push(makeNode({
+                kind: "Incident",
+                external_id: incidentExternalId,
+                title: bugText,
+                properties: { summary: bugText, behavior: reqExternalId },
+                evidence_strength: "hard",
+                review_status: "local_reviewed",
+                confidence: 0.95,
+                provenance: rowProvenance,
+                content_hash: hashString(bugText)
+            }));
+            edges.push(makeEdge({
+                from_external_id: incidentExternalId,
+                to_external_id: reqExternalId,
+                relationship_type: "REGRESSION_OF",
+                evidence_strength: "hard",
+                review_status: "local_reviewed",
+                provenance: rowProvenance
+            }));
+        }
+    }
+    if (reqIndex === 0) {
+        warnings.push(`CSV template '${relPath}' produced no behaviors (no populated 'behavior_name' rows).`);
+    }
+    return { nodes, edges, candidate_edges, sources: [source], warnings };
+}

package/dist/local/enrich/index.js

@@ -0,0 +1,43 @@
+import { enrichFromCsv, looksLikeTemplateHeader } from "./csv.js";
+import { enrichFromMarkdown } from "./markdown.js";
+export { enrichFromCsv } from "./csv.js";
+export { enrichFromMarkdown } from "./markdown.js";
+/** Lowercased file extension including the leading dot (e.g. ".csv"); "" if none. */
+function extensionOf(relPath) {
+    const base = relPath.slice(relPath.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot <= 0 ? "" : base.slice(dot).toLowerCase();
+}
+/** First non-empty line of the content, used for .txt header sniffing. */
+function firstLine(content) {
+    for (const line of content.split(/\r\n|\r|\n/)) {
+        if (line.trim() !== "")
+            return line;
+    }
+    return "";
+}
+/**
+ * Dispatch enrichment by file type.
+ *
+ * `.csv` → CSV template; `.md`/`.mdx`/`.markdown` → Markdown docs. A `.txt`
+ * file whose first line looks like the template header is routed to CSV.
+ * Returns null for unsupported content.
+ */
+export function enrichFromContent(relPath, content) {
+    const ext = extensionOf(relPath);
+    let fragment = null;
+    if (ext === ".csv")
+        fragment = enrichFromCsv(relPath, content);
+    else if (ext === ".md" || ext === ".mdx" || ext === ".markdown")
+        fragment = enrichFromMarkdown(relPath, content);
+    else if (ext === ".txt" && looksLikeTemplateHeader(firstLine(content)))
+        fragment = enrichFromCsv(relPath, content);
+    if (!fragment)
+        return null;
+    // A source that yields zero anchors/evidence is noise — keep the diagnostic
+    // warning but do not register the SourceScope (e.g. a non-template data CSV).
+    if (fragment.nodes.length === 0) {
+        return { nodes: [], edges: [], candidate_edges: [], sources: [], warnings: fragment.warnings };
+    }
+    return fragment;
+}