soturail 0.4.1 → 0.7.0

package/dist/core/context-intelligence.js

@@ -0,0 +1,283 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ensureWorkspace, getWorkspacePaths, loadConfig, readJsonl, relativeToRoot, writeJson } from "./config.js";
+import { scanRepository } from "./file-scanner.js";
+import { RawStore } from "./raw-store.js";
+import { keywordScore, makeRailId, redactProbableSecrets, summarizeText } from "./rail-utils.js";
+import { estimateTokens, tokenEstimateNote } from "./token-estimator.js";
+const roleDefinitions = {
+    planner: {
+        purpose: "Plan work from roadmap, specs, constraints, previous decisions and workflow state.",
+        include: ["README.md", "ROADMAP.md", "docs/", ".soturail/memory/consolidated.jsonl", ".soturail/workflows/"],
+        omit: ["raw logs", "large generated artifacts", "secret-like files"]
+    },
+    executor: {
+        purpose: "Execute a local task with target files, repo map, failing tests and safe commands.",
+        include: [".soturail/indexes/tree.txt", "target files", "tests/", ".soturail/context/selections/"],
+        omit: ["unrelated long docs", "raw logs unless explicitly restored"]
+    },
+    reviewer: {
+        purpose: "Review diffs, tests, rules, acceptance criteria and security notes.",
+        include: ["git diff", "tests/", ".soturail/rules/", ".soturail/harness/failures.jsonl"],
+        omit: ["unchanged dependency trees", "local secrets"]
+    },
+    "release-manager": {
+        purpose: "Prepare release evidence from version, changelog, release notes, package verification and registry state.",
+        include: ["package.json", "CHANGELOG.md", "docs/releases/RELEASE_NOTES_*.md", "docs/release-workflow.md"],
+        omit: ["npm tokens", "browser auth secrets", "raw package caches"]
+    },
+    researcher: {
+        purpose: "Collect local docs, ecosystem notes, comparison constraints and citation reminders.",
+        include: ["docs/", "examples/", "README.md", "ROADMAP.md"],
+        omit: ["uncited claims", "provider secrets", "raw logs"]
+    }
+};
+export async function selectContext(query, limit = 10, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const paths = getWorkspacePaths(root);
+    const config = await loadConfig(root);
+    const repo = await scanRepository(root, config);
+    const route = routeContext(query);
+    const fileItems = await rankFiles(repo.files, query, root);
+    const memoryItems = (await readJsonl(paths.memoryRecordsFile)).map((record) => {
+        const score = keywordScore(query, `${record.text} ${record.tags.join(" ")}`);
+        return {
+            kind: "memory",
+            id: record.id,
+            score: score.score,
+            reason: score.reason,
+            summary: record.text,
+            estimatedTokens: estimateTokens(record.text)
+        };
+    });
+    const selection = {
+        schemaVersion: "soturail.context.selection.v1",
+        id: makeRailId("ctx", query),
+        createdAt: new Date().toISOString(),
+        query,
+        limit,
+        expert: route.expert,
+        role: route.role,
+        items: [...fileItems, ...memoryItems]
+            .filter((item) => item.score > 0)
+            .sort((left, right) => right.score - left.score)
+            .slice(0, limit)
+    };
+    await writeJson(path.join(paths.contextSelectionsDir, `${selection.id}.json`), selection);
+    return selection;
+}
+export function renderSelection(selection) {
+    const lines = [
+        "SotuRail context select",
+        `query: ${selection.query}`,
+        `selection_id: ${selection.id}`,
+        `expert: ${selection.expert}`,
+        `role: ${selection.role}`,
+        `items_count: ${selection.items.length}`,
+        ""
+    ];
+    for (const item of selection.items) {
+        const source = item.path ?? item.id ?? "unknown";
+        lines.push(`- ${item.kind}: ${source}`, `  Score: ${item.score}`, `  Reason: ${item.reason}`, `  Estimated tokens: ${item.estimatedTokens}`, `  Summary: ${item.summary}`, `  Recovery: ${item.kind === "file" ? `open ${source}` : `soturail memory recall "${selection.query}"`}`, "");
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+export async function pruneContext(query, budget = 8000, root = process.cwd()) {
+    const selection = await selectContext(query, 20, root);
+    let used = 0;
+    const included = [];
+    const omitted = [];
+    for (const item of selection.items) {
+        if (used + item.estimatedTokens <= budget) {
+            included.push(item);
+            used += item.estimatedTokens;
+        }
+        else {
+            omitted.push(item);
+        }
+    }
+    const lines = [
+        "SotuRail context prune",
+        `query: ${query}`,
+        `budget_tokens: ${budget}`,
+        `estimated_tokens_used: ${used}`,
+        `selection_id: ${selection.id}`,
+        "",
+        "Included context:"
+    ];
+    for (const item of included) {
+        lines.push(`- ${item.kind}: ${item.path ?? item.id} (${item.estimatedTokens} tokens)`, `  Reason: ${item.reason}`, `  Summary: ${item.summary}`, `  Recovery: ${item.kind === "file" ? `open ${item.path}` : `soturail memory recall "${query}"`}`);
+    }
+    lines.push("", "Omitted context:");
+    for (const item of omitted) {
+        lines.push(`- ${item.kind}: ${item.path ?? item.id} (${item.estimatedTokens} tokens)`, "  Recovery: rerun with a larger --budget or use context restore/offload pointers.");
+    }
+    lines.push("", "Recovery pointers:", `- Full selection: .soturail/context/selections/${selection.id}.json`, "- Long content: soturail context offload <raw-id-or-file>", "- Restore offload: soturail context restore <offload-id>");
+    return `${lines.join("\n")}\n`;
+}
+export async function offloadContext(input, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const paths = getWorkspacePaths(root);
+    let source = input;
+    let content = null;
+    const filePath = path.resolve(root, input);
+    try {
+        content = await fs.readFile(filePath);
+        source = relativeToRoot(root, filePath);
+    }
+    catch {
+        content = await new RawStore(root).readRaw(input);
+        if (!content)
+            throw new Error(`Could not find local file or raw_id: ${input}`);
+        source = `raw_id:${input}`;
+    }
+    const text = redactProbableSecrets(content.toString("utf8"));
+    const id = makeRailId("offload", source);
+    const contentPath = path.join(paths.contextOffloadDir, `${id}.txt`);
+    await fs.writeFile(contentPath, text, "utf8");
+    const record = {
+        schemaVersion: "soturail.context.offload.v1",
+        id,
+        createdAt: new Date().toISOString(),
+        source,
+        path: contentPath,
+        summary: summarizeText(text, 600),
+        bytes: Buffer.byteLength(text, "utf8"),
+        estimatedTokens: estimateTokens(text)
+    };
+    await writeJson(path.join(paths.contextOffloadDir, `${id}.json`), { ...record, path: relativeToRoot(root, contentPath) });
+    return record;
+}
+export async function restoreOffload(id, root = process.cwd()) {
+    const contentPath = path.join(getWorkspacePaths(root).contextOffloadDir, `${id}.txt`);
+    return fs.readFile(contentPath, "utf8").catch((error) => {
+        if (error.code === "ENOENT")
+            throw new Error(`Offload not found: ${id}`);
+        throw error;
+    });
+}
+export async function contextBudget(target = "generic", explain = false, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const paths = getWorkspacePaths(root);
+    const drivers = [
+        await driver("root_agent_docs", root, ["CLAUDE.md", "AGENTS.md", "GEMINI.md"]),
+        await driver("role_packs", root, [relativeToRoot(root, paths.contextRolePacksDir)]),
+        await driver("memory", root, [relativeToRoot(root, paths.memoryRecordsFile), relativeToRoot(root, paths.memoryConsolidatedFile)]),
+        await driver("skills", root, [relativeToRoot(root, paths.skillsDir)]),
+        await driver("mcp_exposure", root, [relativeToRoot(root, paths.mcpExportsDir)]),
+        await driver("raw_logs", root, [relativeToRoot(root, paths.rawIndex)]),
+        await driver("offloaded_logs", root, [relativeToRoot(root, paths.contextOffloadDir)]),
+        await driver("context_packs", root, [relativeToRoot(root, paths.contextDir)]),
+        await driver("run_workspace_evidence", root, [relativeToRoot(root, paths.runsDir), relativeToRoot(root, paths.reportsDir)])
+    ];
+    const total = drivers.reduce((sum, item) => sum + item.estimatedTokens, 0);
+    const lines = [
+        "SotuRail context budget",
+        `target: ${target}`,
+        `estimated_total_tokens: ${total}`,
+        tokenEstimateNote(),
+        "",
+        "Drivers:",
+        ...drivers.map((item) => `- ${item.name}: ${item.estimatedTokens} tokens (${item.paths.join(", ") || "none"})`)
+    ];
+    if (explain) {
+        lines.push("", "Recommendations:", "- Keep root agent docs short and reference richer docs.", "- Use `soturail context pack --role <role>` for scoped planner/executor/reviewer/release-manager/researcher handoffs.", "- Use `soturail context prune` for task handoff.", "- Use `soturail context offload` for long logs and generated artifacts.", "- Keep run workspace evidence local unless a specific artifact is selected.");
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function routeContext(query) {
+    const lower = query.toLowerCase();
+    const candidates = [
+        ["security", "reviewer", /(secret|token|auth|vulnerab|audit|policy|permission|risk)/, "security and policy keyword"],
+        ["release", "release-manager", /(release|publish|npm|version|changelog|tag|github release|pack)/, "release keyword"],
+        ["code", "executor", /(bug|fix|test|build|typescript|code|source|file|function|class|error)/, "code keyword"],
+        ["research", "researcher", /(research|compare|ecosystem|citation)/, "research keyword"],
+        ["docs", "researcher", /(doc|readme|guide|example|copy|wording|tutorial)/, "documentation keyword"],
+        ["workflow", "planner", /(workflow|task|plan|worktree|verify|handoff|run workspace)/, "workflow keyword"],
+        ["memory", "planner", /(memory|remember|recall|decision|fact)/, "memory keyword"]
+    ];
+    const match = candidates.find(([, , pattern]) => pattern.test(lower));
+    return match ? { expert: match[0], role: match[1], reason: match[3] } : { expert: "code", role: "executor", reason: "default local code routing" };
+}
+export async function buildRolePack(role, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const definition = roleDefinitions[role];
+    if (!definition)
+        throw new Error(`Unknown role "${role}".`);
+    const content = [
+        `# SotuRail Role Pack: ${role}`,
+        "",
+        "schemaVersion: soturail.context.role-pack.v1",
+        `createdAt: ${new Date().toISOString()}`,
+        "",
+        "## Purpose",
+        definition.purpose,
+        "",
+        "## Included Sources",
+        ...definition.include.map((item) => `- ${item}`),
+        "",
+        "## Omitted Sources",
+        ...definition.omit.map((item) => `- ${item}`),
+        "",
+        "## Estimated Tokens",
+        `${estimateTokens(definition.purpose + definition.include.join(" ") + definition.omit.join(" "))}`,
+        "",
+        "## Recovery Pointers",
+        "- Regenerate target context packs with `soturail context pack --target all`.",
+        "- Restore offloaded content with `soturail context restore <offload-id>`.",
+        "- Recover raw command output with `soturail expand <raw_id>`.",
+        "",
+        "## Safety Notes",
+        "- Raw logs and secret-like files are not included by default.",
+        "- Use policy approval for publish, global config writes, destructive commands or raw expansion.",
+        ""
+    ].join("\n");
+    const output = path.join(getWorkspacePaths(root).contextRolePacksDir, `${role}.md`);
+    await fs.writeFile(output, content, "utf8");
+    return { path: output, content };
+}
+export function parseRolePack(value) {
+    if (Object.prototype.hasOwnProperty.call(roleDefinitions, value))
+        return value;
+    throw new Error(`Unknown role "${value}". Supported roles: ${Object.keys(roleDefinitions).join(", ")}.`);
+}
+async function rankFiles(files, query, root) {
+    const items = [];
+    for (const file of files) {
+        const score = keywordScore(query, `${file.path} ${file.language} ${file.symbols.map((symbol) => symbol.name).join(" ")}`);
+        if (score.score <= 0)
+            continue;
+        const preview = await fs
+            .readFile(path.resolve(root, file.path), "utf8")
+            .then((raw) => summarizeText(redactProbableSecrets(raw), 300))
+            .catch(() => `${file.language}, ${file.size_bytes} bytes`);
+        items.push({
+            kind: "file",
+            path: file.path,
+            score: score.score,
+            reason: score.reason,
+            summary: preview,
+            estimatedTokens: estimateTokens(preview)
+        });
+    }
+    return items;
+}
+async function driver(name, root, inputs) {
+    let estimatedTokens = 0;
+    const present = [];
+    for (const input of inputs) {
+        const absolute = path.resolve(root, input);
+        const stat = await fs.stat(absolute).catch(() => null);
+        if (!stat)
+            continue;
+        present.push(input);
+        if (stat.isDirectory()) {
+            estimatedTokens += (await fs.readdir(absolute).catch(() => [])).length * 40;
+        }
+        else {
+            estimatedTokens += estimateTokens(await fs.readFile(absolute, "utf8").catch(() => ""));
+        }
+    }
+    return { name, paths: present, estimatedTokens };
+}
+//# sourceMappingURL=context-intelligence.js.map

package/dist/core/context-intelligence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-intelligence.js","sourceRoot":"","sources":["../../src/core/context-intelligence.ts"],"names":[],"mappings":"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"}

package/dist/core/diagram-rail.d.ts

@@ -0,0 +1,31 @@
+import { type DiagramValidationReport } from "./diagram-validator.js";
+export interface DiagramAuditReport {
+    schemaVersion: "soturail.diagram.audit.v1";
+    file: string;
+    exists: boolean;
+    containsMermaid: boolean;
+    fenceOk: boolean;
+    hasSpec: boolean;
+    workflowStateReferenced: boolean;
+    validation: DiagramValidationReport;
+}
+export declare function initDiagramRail(root?: string): Promise<string>;
+export declare function createDiagram(feature: string, root?: string): Promise<{
+    diagramPath: string;
+    specPath: string;
+    output: string;
+}>;
+export declare function auditDiagram(file: string, root?: string): Promise<{
+    report: DiagramAuditReport;
+    output: string;
+}>;
+export declare function validateDiagrams(root?: string): Promise<{
+    reports: DiagramAuditReport[];
+    path: string;
+    output: string;
+}>;
+export declare function diagramFromWorkflow(id: string, root?: string): Promise<{
+    diagramPath: string;
+    specPath: string;
+    output: string;
+}>;

package/dist/core/diagram-rail.js

@@ -0,0 +1,235 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ensureWorkspace, getWorkspacePaths, relativeToRoot, writeJson } from "./config.js";
+import { validateMermaidDiagram } from "./diagram-validator.js";
+import { readWorkflow } from "./workflow-store.js";
+export async function initDiagramRail(root = process.cwd()) {
+    await ensureWorkspace(root);
+    const paths = getWorkspacePaths(root);
+    const docsDir = path.join(root, "docs", "diagrams");
+    await fs.mkdir(paths.diagramsDir, { recursive: true });
+    await fs.mkdir(docsDir, { recursive: true });
+    if (!(await exists(paths.diagramsIndexFile))) {
+        await writeJson(paths.diagramsIndexFile, { schemaVersion: "soturail.diagram.index.v1", diagrams: [] });
+    }
+    await writeFileIfMissing(path.join(docsDir, "README.md"), [
+        "# Diagrams",
+        "",
+        "SotuRail Diagram Rail stores text-based Mermaid diagrams and `.spec.md` visual contracts here.",
+        ""
+    ].join("\n"));
+    return [
+        "SotuRail diagram init",
+        `diagrams_dir: ${relativeToRoot(root, paths.diagramsDir)}`,
+        `docs_diagrams_dir: ${relativeToRoot(root, docsDir)}`,
+        `index: ${relativeToRoot(root, paths.diagramsIndexFile)}`,
+        "next_commands:",
+        "- soturail diagram new <feature>",
+        "- soturail diagram validate"
+    ].join("\n") + "\n";
+}
+export async function createDiagram(feature, root = process.cwd()) {
+    await initDiagramRail(root);
+    const slug = slugify(feature);
+    const title = titleCase(feature);
+    const docsDir = path.join(root, "docs", "diagrams");
+    const diagramPath = path.join(docsDir, `${slug}.md`);
+    const specPath = path.join(docsDir, `${slug}.spec.md`);
+    await writeFileIfMissing(diagramPath, diagramTemplate(title));
+    await writeFileIfMissing(specPath, specTemplate(title, diagramPath, root));
+    await refreshDiagramIndex(root);
+    return {
+        diagramPath,
+        specPath,
+        output: [
+            "SotuRail diagram new",
+            `feature: ${title}`,
+            `diagram: ${relativeToRoot(root, diagramPath)}`,
+            `spec: ${relativeToRoot(root, specPath)}`
+        ].join("\n") + "\n"
+    };
+}
+export async function auditDiagram(file, root = process.cwd()) {
+    const filePath = path.resolve(root, file);
+    const existsFile = await exists(filePath);
+    const raw = existsFile ? await fs.readFile(filePath, "utf8") : "";
+    const specPath = matchingSpecPath(filePath);
+    const report = {
+        schemaVersion: "soturail.diagram.audit.v1",
+        file: relativeToRoot(root, filePath),
+        exists: existsFile,
+        containsMermaid: /```mermaid/i.test(raw),
+        fenceOk: countMatches(raw, /```/g) % 2 === 0,
+        hasSpec: await exists(specPath),
+        workflowStateReferenced: /\b(draft|planned|active|verifying|ready_for_review|closed|blocked)\b/i.test(raw),
+        validation: validateMermaidDiagram(raw)
+    };
+    return { report, output: renderAudit(report) };
+}
+export async function validateDiagrams(root = process.cwd()) {
+    await initDiagramRail(root);
+    const docsDir = path.join(root, "docs", "diagrams");
+    const entries = await listMarkdownFiles(docsDir);
+    const reports = [];
+    for (const entry of entries.filter((file) => !file.endsWith(".spec.md") && path.basename(file) !== "README.md")) {
+        reports.push((await auditDiagram(entry, root)).report);
+    }
+    const outputPath = path.join(getWorkspacePaths(root).diagramsDir, "validation.json");
+    await writeJson(outputPath, { schemaVersion: "soturail.diagram.validation-run.v1", reports });
+    return {
+        reports,
+        path: outputPath,
+        output: [
+            "SotuRail diagram validate",
+            `diagrams_count: ${reports.length}`,
+            `valid_count: ${reports.filter((report) => report.validation.valid && report.fenceOk && report.containsMermaid).length}`,
+            `report: ${relativeToRoot(root, outputPath)}`,
+            "",
+            ...reports.map((report) => `- ${report.file}: ${report.validation.valid && report.fenceOk && report.containsMermaid ? "valid" : "warn"}`)
+        ].join("\n") + "\n"
+    };
+}
+export async function diagramFromWorkflow(id, root = process.cwd()) {
+    await initDiagramRail(root);
+    const workflow = await readWorkflow(id, root);
+    const slug = slugify(workflow.id);
+    const title = `Workflow ${workflow.title}`;
+    const docsDir = path.join(root, "docs", "diagrams");
+    const diagramPath = path.join(docsDir, `${slug}.md`);
+    const specPath = path.join(docsDir, `${slug}.spec.md`);
+    const diagram = [
+        `# ${title}`,
+        "",
+        "```mermaid",
+        "stateDiagram-v2",
+        "  [*] --> draft",
+        "  draft --> planned",
+        "  planned --> active",
+        "  active --> verifying",
+        "  verifying --> ready_for_review",
+        "  ready_for_review --> closed",
+        "  verifying --> blocked",
+        `  ${workflow.state} --> ${workflow.state}`,
+        "```",
+        "",
+        `workflow_id: ${workflow.id}`,
+        `current_state: ${workflow.state}`,
+        ""
+    ].join("\n");
+    await fs.writeFile(diagramPath, diagram, "utf8");
+    await writeFileIfMissing(specPath, specTemplate(title, diagramPath, root));
+    await refreshDiagramIndex(root);
+    return {
+        diagramPath,
+        specPath,
+        output: [
+            "SotuRail diagram from-workflow",
+            `workflow_id: ${workflow.id}`,
+            `diagram: ${relativeToRoot(root, diagramPath)}`,
+            `spec: ${relativeToRoot(root, specPath)}`
+        ].join("\n") + "\n"
+    };
+}
+function renderAudit(report) {
+    return [
+        "SotuRail diagram audit",
+        `file: ${report.file}`,
+        `exists: ${report.exists}`,
+        `contains_mermaid: ${report.containsMermaid}`,
+        `fence_ok: ${report.fenceOk}`,
+        `matching_spec: ${report.hasSpec}`,
+        `workflow_state_referenced: ${report.workflowStateReferenced}`,
+        `valid: ${report.validation.valid}`,
+        "",
+        ...(report.validation.findings.length > 0 ? report.validation.findings.map((finding) => `- ${finding.severity}: ${finding.message}`) : ["No validation findings."])
+    ].join("\n") + "\n";
+}
+async function refreshDiagramIndex(root) {
+    const docsDir = path.join(root, "docs", "diagrams");
+    const diagrams = (await listMarkdownFiles(docsDir)).filter((file) => !file.endsWith(".spec.md"));
+    await writeJson(getWorkspacePaths(root).diagramsIndexFile, { schemaVersion: "soturail.diagram.index.v1", diagrams });
+}
+async function listMarkdownFiles(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+        .map((entry) => path.join(dir, entry.name))
+        .sort((left, right) => left.localeCompare(right));
+}
+function diagramTemplate(title) {
+    return [
+        `# Diagram: ${title}`,
+        "",
+        "```mermaid",
+        "stateDiagram-v2",
+        "  [*] --> Draft",
+        "  Draft --> Planned",
+        "  Planned --> Active",
+        "  Active --> Verifying",
+        "  Verifying --> ReadyForReview",
+        "  ReadyForReview --> Closed",
+        "  Verifying --> Blocked",
+        "```",
+        ""
+    ].join("\n");
+}
+function specTemplate(title, diagramPath, root) {
+    return [
+        `# Visual Contract: ${title}`,
+        "",
+        "## Required nodes",
+        "",
+        "- Draft",
+        "- Planned",
+        "- Active",
+        "- Verifying",
+        "- ReadyForReview",
+        "- Closed",
+        "- Blocked",
+        "",
+        "## Required transitions",
+        "",
+        "- Draft -> Planned",
+        "- Planned -> Active",
+        "- Active -> Verifying",
+        "- Verifying -> ReadyForReview",
+        "- ReadyForReview -> Closed",
+        "",
+        "## Evidence links",
+        "",
+        `- Diagram: ${relativeToRoot(root, diagramPath)}`,
+        "- Workflow evidence: run `soturail workflow evidence <id>` when available.",
+        "",
+        "## Validation checklist",
+        "",
+        "- [ ] Mermaid block is present.",
+        "- [ ] Verification transition is present.",
+        "- [ ] Tests and evidence are linked before release.",
+        "",
+        "## Known gaps",
+        "",
+        "- Add feature-specific states and acceptance evidence.",
+        ""
+    ].join("\n");
+}
+function matchingSpecPath(filePath) {
+    return filePath.endsWith(".spec.md") ? filePath : filePath.replace(/\.md$/i, ".spec.md");
+}
+function countMatches(value, pattern) {
+    return [...value.matchAll(pattern)].length;
+}
+async function writeFileIfMissing(filePath, content) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    if (!(await exists(filePath)))
+        await fs.writeFile(filePath, content, "utf8");
+}
+async function exists(filePath) {
+    return fs.access(filePath).then(() => true).catch(() => false);
+}
+function slugify(input) {
+    return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "diagram";
+}
+function titleCase(input) {
+    return input.trim().replace(/\s+/g, " ").replace(/\b\w/g, (match) => match.toUpperCase()) || "Diagram";
+}
+//# sourceMappingURL=diagram-rail.js.map

package/dist/core/diagram-rail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagram-rail.js","sourceRoot":"","sources":["../../src/core/diagram-rail.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,sBAAsB,EAAgC,MAAM,wBAAwB,CAAC;AAC9F,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAanD,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IACxD,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IACpD,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,EAAE,CAAC;QAC7C,MAAM,SAAS,CAAC,KAAK,CAAC,iBAAiB,EAAE,EAAE,aAAa,EAAE,2BAA2B,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;IACzG,CAAC;IACD,MAAM,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE;QACxD,YAAY;QACZ,EAAE;QACF,gGAAgG;QAChG,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACd,OAAO;QACL,uBAAuB;QACvB,iBAAiB,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,EAAE;QAC1D,sBAAsB,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE;QACrD,UAAU,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,iBAAiB,CAAC,EAAE;QACzD,gBAAgB;QAChB,kCAAkC;QAClC,6BAA6B;KAC9B,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACtB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAe,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IACvE,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IACjC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IACpD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,UAAU,CAAC,CAAC;IACvD,MAAM,kBAAkB,CAAC,WAAW,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9D,MAAM,kBAAkB,CAAC,QAAQ,EAAE,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC;IAC3E,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO;QACL,WAAW;QACX,QAAQ;QACR,MAAM,EAAE;YACN,sBAAsB;YACtB,YAAY,KAAK,EAAE;YACnB,YAAY,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE;YAC/C,SAAS,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE;SAC1C,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI;KACpB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IACnE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClE,MAAM,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAuB;QACjC,aAAa,EAAE,2BAA2B;QAC1C,IAAI,EAAE,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC;QACpC,MAAM,EAAE,UAAU;QAClB,eAAe,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;QACxC,OAAO,EAAE,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;QAC5C,OAAO,EAAE,MAAM,MAAM,CAAC,QAAQ,CAAC;QAC/B,uBAAuB,EAAE,uEAAuE,CAAC,IAAI,CAAC,GAAG,CAAC;QAC1G,UAAU,EAAE,sBAAsB,CAAC,GAAG,CAAC;KACxC,CAAC;IACF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IACzD,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,EAAE,CAAC;IACnB,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,WAAW,CAAC,EAAE,CAAC;QAChH,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC;IACrF,MAAM,SAAS,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,oCAAoC,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9F,OAAO;QACL,OAAO;QACP,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE;YACN,2BAA2B;YAC3B,mBAAmB,OAAO,CAAC,MAAM,EAAE;YACnC,gBAAgB,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,eAAe,CAAC,CAAC,MAAM,EAAE;YACxH,WAAW,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE;YAC7C,EAAE;YACF,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,UAAU,CAAC,KAAK,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SAC1I,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI;KACpB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAU,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IACxE,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,YAAY,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IACpD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,UAAU,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG;QACd,KAAK,KAAK,EAAE;QACZ,EAAE;QACF,YAAY;QACZ,iBAAiB;QACjB,iBAAiB;QACjB,qBAAqB;QACrB,sBAAsB;QACtB,wBAAwB;QACxB,kCAAkC;QAClC,+BAA+B;QAC/B,yBAAyB;QACzB,KAAK,QAAQ,CAAC,KAAK,QAAQ,QAAQ,CAAC,KAAK,EAAE;QAC3C,KAAK;QACL,EAAE;QACF,gBAAgB,QAAQ,CAAC,EAAE,EAAE;QAC7B,kBAAkB,QAAQ,CAAC,KAAK,EAAE;QAClC,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,MAAM,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACjD,MAAM,kBAAkB,CAAC,QAAQ,EAAE,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC;IAC3E,MAAM,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO;QACL,WAAW;QACX,QAAQ;QACR,MAAM,EAAE;YACN,gCAAgC;YAChC,gBAAgB,QAAQ,CAAC,EAAE,EAAE;YAC7B,YAAY,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE;YAC/C,SAAS,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE;SAC1C,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI;KACpB,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,MAA0B;IAC7C,OAAO;QACL,wBAAwB;QACxB,SAAS,MAAM,CAAC,IAAI,EAAE;QACtB,WAAW,MAAM,CAAC,MAAM,EAAE;QAC1B,qBAAqB,MAAM,CAAC,eAAe,EAAE;QAC7C,aAAa,MAAM,CAAC,OAAO,EAAE;QAC7B,kBAAkB,MAAM,CAAC,OAAO,EAAE;QAClC,8BAA8B,MAAM,CAAC,uBAAuB,EAAE;QAC9D,UAAU,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE;QACnC,EAAE;QACF,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC;KACpK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACtB,CAAC;AAED,KAAK,UAAU,mBAAmB,CAAC,IAAY;IAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,CAAC,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;IACjG,MAAM,SAAS,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,iBAAiB,EAAE,EAAE,aAAa,EAAE,2BAA2B,EAAE,QAAQ,EAAE,CAAC,CAAC;AACvH,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,GAAW;IAC1C,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAC/E,OAAO,OAAO;SACX,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SAC/D,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;SAC1C,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO;QACL,cAAc,KAAK,EAAE;QACrB,EAAE;QACF,YAAY;QACZ,iBAAiB;QACjB,iBAAiB;QACjB,qBAAqB;QACrB,sBAAsB;QACtB,wBAAwB;QACxB,gCAAgC;QAChC,6BAA6B;QAC7B,yBAAyB;QACzB,KAAK;QACL,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,YAAY,CAAC,KAAa,EAAE,WAAmB,EAAE,IAAY;IACpE,OAAO;QACL,sBAAsB,KAAK,EAAE;QAC7B,EAAE;QACF,mBAAmB;QACnB,EAAE;QACF,SAAS;QACT,WAAW;QACX,UAAU;QACV,aAAa;QACb,kBAAkB;QAClB,UAAU;QACV,WAAW;QACX,EAAE;QACF,yBAAyB;QACzB,EAAE;QACF,oBAAoB;QACpB,qBAAqB;QACrB,uBAAuB;QACvB,+BAA+B;QAC/B,4BAA4B;QAC5B,EAAE;QACF,mBAAmB;QACnB,EAAE;QACF,cAAc,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE;QACjD,4EAA4E;QAC5E,EAAE;QACF,yBAAyB;QACzB,EAAE;QACF,iCAAiC;QACjC,2CAA2C;QAC3C,qDAAqD;QACrD,EAAE;QACF,eAAe;QACf,EAAE;QACF,wDAAwD;QACxD,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAgB;IACxC,OAAO,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC3F,CAAC;AAED,SAAS,YAAY,CAAC,KAAa,EAAE,OAAe;IAClD,OAAO,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AAC7C,CAAC;AAED,KAAK,UAAU,kBAAkB,CAAC,QAAgB,EAAE,OAAe;IACjE,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QAAE,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC/E,CAAC;AAED,KAAK,UAAU,MAAM,CAAC,QAAgB;IACpC,OAAO,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC;AAED,SAAS,OAAO,CAAC,KAAa;IAC5B,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC;AAC3G,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,SAAS,CAAC;AACzG,CAAC"}

package/dist/core/diagram-validator.d.ts

@@ -0,0 +1,10 @@
+export interface DiagramValidationFinding {
+    severity: "error" | "warning";
+    message: string;
+}
+export interface DiagramValidationReport {
+    schemaVersion: "soturail.diagram.validation.v1";
+    valid: boolean;
+    findings: DiagramValidationFinding[];
+}
+export declare function validateMermaidDiagram(input: string): DiagramValidationReport;

package/dist/core/diagram-validator.js

@@ -0,0 +1,53 @@
+export function validateMermaidDiagram(input) {
+    const findings = [];
+    const text = extractMermaid(input);
+    if (!text.trim()) {
+        findings.push({ severity: "error", message: "No Mermaid content found." });
+        return { schemaVersion: "soturail.diagram.validation.v1", valid: false, findings };
+    }
+    if (!/^\s*(stateDiagram-v2|flowchart\s+(TD|LR|BT|RL)|graph\s+(TD|LR|BT|RL))/m.test(text)) {
+        findings.push({ severity: "error", message: "Diagram must start with a supported Mermaid stateDiagram, flowchart, or graph declaration." });
+    }
+    if (/stateDiagram-v2/.test(text)) {
+        if (!/\[\*\]\s*-->/.test(text))
+            findings.push({ severity: "warning", message: "State diagram is missing an initial transition." });
+        if (!/-->\s*Verifying|Verifying\s*-->/.test(text))
+            findings.push({ severity: "warning", message: "State diagram is missing a verification transition." });
+        const states = collectStateNames(text);
+        const targets = collectTargetStateNames(text);
+        for (const state of states) {
+            if (!targets.has(state) && !/Draft|Start|\[\*\]/i.test(state)) {
+                findings.push({ severity: "warning", message: `State may be unreachable: ${state}` });
+            }
+        }
+    }
+    if (/flowchart|graph/.test(text) && /Publish|Release|NpmPublish|GitHubRelease/i.test(text) && !/Test|Audit|Pack|Verify/i.test(text)) {
+        findings.push({ severity: "warning", message: "Release diagram should include test/audit/pack verification before publish/release." });
+    }
+    return {
+        schemaVersion: "soturail.diagram.validation.v1",
+        valid: findings.every((finding) => finding.severity !== "error"),
+        findings
+    };
+}
+function extractMermaid(input) {
+    const match = input.match(/```mermaid\s*([\s\S]*?)```/i);
+    return match?.[1] ?? input;
+}
+function collectStateNames(text) {
+    const states = new Set();
+    for (const match of text.matchAll(/^\s*([A-Za-z][\w-]*)\s*-->/gm)) {
+        if (match[1])
+            states.add(match[1]);
+    }
+    return states;
+}
+function collectTargetStateNames(text) {
+    const states = new Set();
+    for (const match of text.matchAll(/-->\s*([A-Za-z][\w-]*)/g)) {
+        if (match[1])
+            states.add(match[1]);
+    }
+    return states;
+}
+//# sourceMappingURL=diagram-validator.js.map