@archrad/deterministic 0.1.4 → 0.1.6

package/dist/mcp-server.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+/**
+ * archrad-mcp — Model Context Protocol server (stdio) for deterministic IR validation,
+ * architecture lint, policy packs, and drift checks. Uses the same engine as `archrad` CLI.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { normalizeIrGraph, validateIrStructural, validateIrLint, runValidateDrift, sortFindings, loadPolicyPacksFromDirectory, loadPolicyPacksFromFiles, } from './index.js';
+import { getStaticRuleGuidance, listStaticRuleCodes } from './static-rule-guidance.js';
+import { MCP_TOOL_ARCHRAD_LIST_RULE_CODES, MCP_TOOL_ARCHRAD_LINT_SUMMARY, MCP_TOOL_ARCHRAD_POLICY_PACKS_LOAD, MCP_TOOL_ARCHRAD_SUGGEST_FIX, MCP_TOOL_ARCHRAD_VALIDATE_DRIFT, MCP_TOOL_ARCHRAD_VALIDATE_IR, } from './mcp-server-tools-patch.js';
+const VERSION = '0.1.6';
+/** Hard cap for `irPath` reads (see docs/MCP.md). */
+const MAX_IR_FILE_BYTES = 25 * 1024 * 1024;
+function jsonResult(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+}
+async function loadIrFromArgs(args) {
+    const hasInline = args.ir !== undefined;
+    const hasPath = args.irPath != null && String(args.irPath).trim() !== '';
+    if (hasInline && hasPath) {
+        return { ok: false, error: 'Provide only one of `ir` or `irPath`.' };
+    }
+    if (hasPath) {
+        const p = resolve(args.irPath);
+        let st;
+        try {
+            st = await stat(p);
+        }
+        catch (e) {
+            return { ok: false, error: `irPath not readable: ${e instanceof Error ? e.message : String(e)}` };
+        }
+        if (!st.isFile()) {
+            return { ok: false, error: `irPath is not a file: ${p}` };
+        }
+        if (st.size > MAX_IR_FILE_BYTES) {
+            return {
+                ok: false,
+                error: `IR file is ${st.size} bytes (max ${MAX_IR_FILE_BYTES}). Split the graph, trim fixtures, or validate smaller subgraphs.`,
+            };
+        }
+        const raw = await readFile(p, 'utf8');
+        try {
+            return { ok: true, ir: JSON.parse(raw) };
+        }
+        catch (e) {
+            return { ok: false, error: `Invalid JSON in irPath: ${e instanceof Error ? e.message : String(e)}` };
+        }
+    }
+    if (hasInline) {
+        return { ok: true, ir: args.ir };
+    }
+    return { ok: false, error: 'Provide `ir` (inline JSON) or `irPath` (path to IR JSON file).' };
+}
+async function main() {
+    const server = new McpServer({
+        name: 'archrad-deterministic',
+        version: VERSION,
+    });
+    server.registerTool('archrad_validate_ir', {
+        title: MCP_TOOL_ARCHRAD_VALIDATE_IR.title,
+        description: MCP_TOOL_ARCHRAD_VALIDATE_IR.description,
+        inputSchema: {
+            ir: z.unknown().optional().describe('Inline IR graph as a JSON object. Use for small graphs only.'),
+            irPath: z.string().optional().describe('Absolute or relative path to an IR JSON file. Preferred for large graphs.'),
+            policiesDirectory: z
+                .string()
+                .optional()
+                .describe('Path to a directory of PolicyPack YAML/JSON files. Optional — omit if you have no custom rules.'),
+        },
+    }, async (args) => {
+        const loaded = await loadIrFromArgs(args);
+        if (!loaded.ok)
+            return jsonResult({ ok: false, phase: 'input', error: loaded.error });
+        const irRaw = loaded.ir;
+        const norm = normalizeIrGraph(irRaw);
+        if ('findings' in norm) {
+            return jsonResult({ ok: false, phase: 'normalize', findings: norm.findings });
+        }
+        const structural = validateIrStructural(irRaw);
+        let policyRuleVisitors;
+        if (args.policiesDirectory) {
+            const dir = resolve(args.policiesDirectory);
+            const packLoaded = await loadPolicyPacksFromDirectory(dir);
+            if (!packLoaded.ok) {
+                return jsonResult({ ok: false, phase: 'policy_packs', errors: packLoaded.errors });
+            }
+            policyRuleVisitors = packLoaded.visitors;
+        }
+        const irLintFindings = validateIrLint(irRaw, { policyRuleVisitors });
+        const combined = sortFindings([...structural, ...irLintFindings]);
+        return jsonResult({
+            ok: combined.every((f) => f.severity !== 'error'),
+            irStructuralFindings: structural,
+            irLintFindings,
+            combined,
+        });
+    });
+    server.registerTool('archrad_lint_summary', {
+        title: MCP_TOOL_ARCHRAD_LINT_SUMMARY.title,
+        description: MCP_TOOL_ARCHRAD_LINT_SUMMARY.description,
+        inputSchema: {
+            ir: z.unknown().optional().describe('Inline IR graph as a JSON object.'),
+            irPath: z.string().optional().describe('Absolute or relative path to an IR JSON file.'),
+            policiesDirectory: z
+                .string()
+                .optional()
+                .describe('Path to a directory of PolicyPack YAML/JSON files. Optional.'),
+        },
+    }, async (args) => {
+        const loaded = await loadIrFromArgs(args);
+        if (!loaded.ok)
+            return jsonResult({ summary: loaded.error });
+        const irRaw = loaded.ir;
+        const norm = normalizeIrGraph(irRaw);
+        if ('findings' in norm) {
+            return jsonResult({ summary: `Normalize failed: ${norm.findings.map((f) => f.message).join('; ')}` });
+        }
+        const structural = validateIrStructural(irRaw);
+        let policyRuleVisitors;
+        if (args.policiesDirectory) {
+            const packLoaded = await loadPolicyPacksFromDirectory(resolve(args.policiesDirectory));
+            if (!packLoaded.ok) {
+                return jsonResult({ summary: `Policy packs failed: ${packLoaded.errors.join('; ')}` });
+            }
+            policyRuleVisitors = packLoaded.visitors;
+        }
+        const irLintFindings = validateIrLint(irRaw, { policyRuleVisitors });
+        const combined = sortFindings([...structural, ...irLintFindings]);
+        const errors = combined.filter((f) => f.severity === 'error');
+        const warnings = combined.filter((f) => f.severity === 'warning');
+        const lines = [
+            `Findings: ${combined.length} (${errors.length} errors, ${warnings.length} warnings).`,
+            ...combined.slice(0, 20).map((f) => `- [${f.code}] ${f.message}`),
+        ];
+        if (combined.length > 20)
+            lines.push(`… and ${combined.length - 20} more.`);
+        return jsonResult({
+            summary: lines.join('\n'),
+            counts: { total: combined.length, errors: errors.length, warnings: warnings.length },
+        });
+    });
+    server.registerTool('archrad_suggest_fix', {
+        title: MCP_TOOL_ARCHRAD_SUGGEST_FIX.title,
+        description: MCP_TOOL_ARCHRAD_SUGGEST_FIX.description,
+        inputSchema: {
+            findingCode: z.string().min(1).describe('The finding code to look up, e.g. "IR-LINT-MISSING-AUTH-010".'),
+        },
+    }, async (args) => {
+        const g = getStaticRuleGuidance(args.findingCode);
+        if (!g) {
+            return jsonResult({
+                ok: false,
+                findingCode: args.findingCode,
+                error: 'Unknown built-in code. PolicyPack and org rules use custom rule ids in YAML — see your pack. Call archrad_list_rule_codes to see all built-in codes with static guidance.',
+            });
+        }
+        return jsonResult({ ok: true, ...g });
+    });
+    server.registerTool('archrad_list_rule_codes', {
+        title: MCP_TOOL_ARCHRAD_LIST_RULE_CODES.title,
+        description: MCP_TOOL_ARCHRAD_LIST_RULE_CODES.description,
+        inputSchema: {},
+    }, async () => jsonResult({ codes: listStaticRuleCodes() }));
+    server.registerTool('archrad_validate_drift', {
+        title: MCP_TOOL_ARCHRAD_VALIDATE_DRIFT.title,
+        description: MCP_TOOL_ARCHRAD_VALIDATE_DRIFT.description,
+        inputSchema: {
+            ir: z.unknown().optional().describe('Inline IR graph as a JSON object.'),
+            irPath: z.string().optional().describe('Absolute or relative path to an IR JSON file.'),
+            target: z
+                .enum(['python', 'nodejs'])
+                .describe('Export target language. Use "nodejs" for Node.js/TypeScript, "python" for Python.'),
+            exportDir: z
+                .string()
+                .describe('Absolute path to the on-disk export directory to compare against the IR.'),
+            policiesDirectory: z.string().optional().describe('Path to a PolicyPack directory. Optional.'),
+            skipIrLint: z.boolean().optional().describe('Set to true to skip IR-LINT checks and only check for drift. Default: false.'),
+        },
+    }, async (args) => {
+        const loaded = await loadIrFromArgs(args);
+        if (!loaded.ok)
+            return jsonResult({ ok: false, phase: 'input', error: loaded.error });
+        const irRaw = loaded.ir;
+        const norm = normalizeIrGraph(irRaw);
+        if ('findings' in norm) {
+            return jsonResult({ ok: false, phase: 'normalize', findings: norm.findings });
+        }
+        const actualIR = irRaw && typeof irRaw === 'object' && irRaw !== null && 'graph' in irRaw
+            ? irRaw
+            : { graph: norm.graph };
+        let policyRuleVisitors;
+        if (args.policiesDirectory) {
+            const packLoaded = await loadPolicyPacksFromDirectory(resolve(args.policiesDirectory));
+            if (!packLoaded.ok) {
+                return jsonResult({ ok: false, phase: 'policy_packs', errors: packLoaded.errors });
+            }
+            policyRuleVisitors = packLoaded.visitors;
+        }
+        const outDir = resolve(args.exportDir);
+        const result = await runValidateDrift(actualIR, args.target, outDir, {
+            skipIrLint: args.skipIrLint ?? false,
+            policyRuleVisitors,
+        });
+        return jsonResult({
+            ok: result.ok,
+            driftFindings: result.driftFindings,
+            extraBlocking: result.extraBlocking,
+            irStructuralFindings: result.exportResult.irStructuralFindings,
+            irLintFindings: result.exportResult.irLintFindings,
+        });
+    });
+    server.registerTool('archrad_policy_packs_load', {
+        title: MCP_TOOL_ARCHRAD_POLICY_PACKS_LOAD.title,
+        description: MCP_TOOL_ARCHRAD_POLICY_PACKS_LOAD.description,
+        inputSchema: {
+            directory: z.string().optional().describe('Path to a directory of PolicyPack YAML/JSON files.'),
+            files: z
+                .array(z.object({
+                name: z.string().describe('Filename, e.g. "auth-rules.yaml".'),
+                content: z.string().describe('Raw file content as a string.'),
+            }))
+                .optional()
+                .describe('In-memory file list. Use when you have policy content as strings rather than on-disk files.'),
+        },
+    }, async (args) => {
+        if (args.files && args.files.length > 0) {
+            const loaded = loadPolicyPacksFromFiles(args.files.map((f) => ({ name: f.name, content: f.content })));
+            if (!loaded.ok) {
+                return jsonResult({ ok: false, errors: loaded.errors });
+            }
+            return jsonResult({ ok: true, ruleCount: loaded.ruleCount });
+        }
+        if (args.directory) {
+            const loaded = await loadPolicyPacksFromDirectory(resolve(args.directory));
+            if (!loaded.ok) {
+                return jsonResult({ ok: false, errors: loaded.errors });
+            }
+            return jsonResult({ ok: true, ruleCount: loaded.ruleCount });
+        }
+        return jsonResult({
+            ok: false,
+            error: 'Provide either directory (path string) or files (array of {name, content}).',
+        });
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('archrad-mcp:', err);
+    process.exitCode = 1;
+});

package/dist/nodeExpress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodeExpress.d.ts","sourceRoot":"","sources":["../src/nodeExpress.ts"],"names":[],"mappings":"AAIA,wBAA8B,wBAAwB,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAE,GAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,CAuapH"}
+{"version":3,"file":"nodeExpress.d.ts","sourceRoot":"","sources":["../src/nodeExpress.ts"],"names":[],"mappings":"AAKA,wBAA8B,wBAAwB,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAE,GAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,CA0apH"}

package/dist/nodeExpress.js

@@ -1,6 +1,7 @@
 // Deterministic Node Express exporter (skeleton)
 // Exports a map of filename -> content for a generated Express app.
 import { getEdgeConfig, generateRetryCode, generateCircuitBreakerCode } from './edgeConfigCodeGenerator.js';
+import { MAX_UNTRUSTED_STRING_LEN, stripLeadingTrailingHyphens } from './stringEdgeStrip.js';
 export default async function generateNodeExpressFiles(actualIR, opts = {}) {
     const files = {};
     const graph = (actualIR && actualIR.graph) ? actualIR.graph : (actualIR || {});
@@ -12,7 +13,10 @@ export default async function generateNodeExpressFiles(actualIR, opts = {}) {
     const nonHttpNodes = [];
     // Track edge config utilities (retry, circuit breaker) to include once
     const edgeUtilityCode = new Set();
-    function safeId(id) { return String(id || '').replace(/[^A-Za-z0-9_\-]/g, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'node'; }
+    function safeId(id) {
+        const raw = String(id || '').slice(0, MAX_UNTRUSTED_STRING_LEN);
+        return stripLeadingTrailingHyphens(raw.replace(/[^A-Za-z0-9_\-]/g, '-')).toLowerCase() || 'node';
+    }
     function handlerName(n) { return `handler_${safeId(n && (n.id || n.name))}`.replace(/-/g, '_'); }
     /**
      * Generate code for inner nodes (support nodes) that are embedded within a key node

package/dist/openapi-to-ir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-to-ir.d.ts","sourceRoot":"","sources":["../src/openapi-to-ir.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAuBD,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,EAAE,CAqD1F;AAyDD;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgClG;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMnF;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQnF"}
+{"version":3,"file":"openapi-to-ir.d.ts","sourceRoot":"","sources":["../src/openapi-to-ir.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AA0BD,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,EAAE,CAqD1F;AAyDD;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgClG;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMnF;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQnF"}

package/dist/openapi-to-ir.js

@@ -4,6 +4,7 @@
  * This is not semantic architecture truth — only operations under `paths` become `http` nodes.
  */
 import { parseOpenApiString, validateOpenApiStructural } from './openapi-structural.js';
+import { MAX_UNTRUSTED_STRING_LEN, stripLeadingTrailingHyphens, stripLeadingTrailingUnderscores } from './stringEdgeStrip.js';
 export class OpenApiIngestError extends Error {
     constructor(message) {
         super(message);
@@ -16,15 +17,16 @@ function normalizeOpenApiPath(pathKey) {
     return s.startsWith('/') ? s : `/${s}`;
 }
 function safeServiceName(title) {
-    const t = String(title || 'openapi-service')
+    const t = stripLeadingTrailingHyphens(String(title || 'openapi-service')
         .trim()
-        .replace(/[^a-zA-Z0-9_-]+/g, '-')
-        .replace(/^-+|-+$/g, '')
+        .slice(0, 256)
+        .replace(/[^a-zA-Z0-9_-]+/g, '-'))
         .toLowerCase();
     return t.slice(0, 63) || 'openapi-service';
 }
 function safeNodeId(path, method) {
-    const slug = `${method}_${path}`.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_|_$/g, '').toLowerCase();
+    const combined = `${method}_${path}`.slice(0, MAX_UNTRUSTED_STRING_LEN);
+    const slug = stripLeadingTrailingUnderscores(combined.replace(/[^a-zA-Z0-9]+/g, '_')).toLowerCase();
     return `openapi_${slug || 'route'}`.slice(0, 80);
 }
 /**

package/dist/pythonFastAPI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pythonFastAPI.d.ts","sourceRoot":"","sources":["../src/pythonFastAPI.ts"],"names":[],"mappings":"AA4OA,wBAA8B,0BAA0B,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAE,GAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,CA2ctH"}
+{"version":3,"file":"pythonFastAPI.d.ts","sourceRoot":"","sources":["../src/pythonFastAPI.ts"],"names":[],"mappings":"AA8OA,wBAA8B,0BAA0B,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAE,GAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,CA2ctH"}

package/dist/pythonFastAPI.js

@@ -1,8 +1,10 @@
 // Deterministic Python FastAPI exporter
 // Produces a map of filename -> content given an IR (plan graph) and options.
 import { getEdgeConfig, generateRetryCode, generateCircuitBreakerCode } from './edgeConfigCodeGenerator.js';
+import { MAX_UNTRUSTED_STRING_LEN, stripLeadingTrailingHyphens } from './stringEdgeStrip.js';
 function safeId(id) {
-    return String(id || '').replace(/[^A-Za-z0-9_\-]/g, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'node';
+    const raw = String(id || '').slice(0, MAX_UNTRUSTED_STRING_LEN);
+    return stripLeadingTrailingHyphens(raw.replace(/[^A-Za-z0-9_\-]/g, '-')).toLowerCase() || 'node';
 }
 function handlerNameFor(n) {
     if (n && n.config && n.config.name)

package/dist/static-rule-guidance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Static, deterministic remediation text for built-in finding codes (IR-STRUCT-*, IR-LINT-*, DRIFT-*).
+ * Used by MCP `archrad_suggest_fix` — not generated architecture; same hints the engine documents in findings.
+ */
+export type StaticRuleGuidance = {
+    findingCode: string;
+    title: string;
+    remediation: string;
+    /** Canonical docs path (no analytics/query params). */
+    docsUrl: string;
+};
+/** Public OSS repo (subtree); `docs/` is at repo root in arch-deterministic. */
+export declare const RULE_CODES_DOC_BASE = "https://github.com/archradhq/arch-deterministic/blob/main/docs/RULE_CODES.md";
+/** GitHub heading anchor (must match markdown `## CODE` in docs/RULE_CODES.md). */
+export declare function githubRuleCodeAnchor(code: string): string;
+export declare function docsUrlForFindingCode(code: string): string;
+export declare function listStaticRuleCodes(): string[];
+export declare function getStaticRuleGuidance(findingCode: string): StaticRuleGuidance | null;
+//# sourceMappingURL=static-rule-guidance.d.ts.map

package/dist/static-rule-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-rule-guidance.d.ts","sourceRoot":"","sources":["../src/static-rule-guidance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,iFACgD,CAAC;AAEjF,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AA2KD,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C;AAED,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CASpF"}

package/dist/static-rule-guidance.js

@@ -0,0 +1,165 @@
+/**
+ * Static, deterministic remediation text for built-in finding codes (IR-STRUCT-*, IR-LINT-*, DRIFT-*).
+ * Used by MCP `archrad_suggest_fix` — not generated architecture; same hints the engine documents in findings.
+ */
+/** Public OSS repo (subtree); `docs/` is at repo root in arch-deterministic. */
+export const RULE_CODES_DOC_BASE = 'https://github.com/archradhq/arch-deterministic/blob/main/docs/RULE_CODES.md';
+/** GitHub heading anchor (must match markdown `## CODE` in docs/RULE_CODES.md). */
+export function githubRuleCodeAnchor(code) {
+    return code
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+export function docsUrlForFindingCode(code) {
+    return `${RULE_CODES_DOC_BASE}#${githubRuleCodeAnchor(code)}`;
+}
+/** Built-in codes with curated guidance. Org PolicyPack codes (e.g. ORG-*) are not listed here. */
+const GUIDANCE = {
+    'IR-LINT-DIRECT-DB-ACCESS-002': {
+        title: 'HTTP-like node connects directly to a datastore',
+        remediation: 'Introduce a service or domain layer between HTTP handlers and persistence: add intermediate nodes and edges so the API does not couple directly to a single DB node. This preserves testability, storage swaps, and invariant enforcement at a clear boundary.',
+    },
+    'IR-LINT-HIGH-FANOUT-004': {
+        title: 'High outgoing dependency count',
+        remediation: 'Reduce fan-out: split responsibilities, add a facade, batch calls, or use async handoff (queues) so one node does not synchronously depend on many downstreams. High fan-out increases blast radius and latency under load.',
+    },
+    'IR-LINT-SYNC-CHAIN-001': {
+        title: 'Long synchronous chain from HTTP entry',
+        remediation: 'Shorten the synchronous call graph or mark non-blocking hops as async: set `metadata.protocol` / edge metadata for async boundaries, or `config.async` where applicable, so depth reflects real execution. Deep sync chains amplify latency and failures.',
+    },
+    'IR-LINT-NO-HEALTHCHECK-003': {
+        title: 'No typical health/readiness route on HTTP nodes',
+        remediation: 'Add at least one GET route such as `/health` or `/ready` on an HTTP node (or document a dedicated health node). Orchestrators and load balancers rely on these for safe deploys and rollbacks.',
+    },
+    'IR-LINT-ISOLATED-NODE-005': {
+        title: 'Node has no incident edges',
+        remediation: 'Remove the orphan or connect it with edges so it participates in the architecture. Isolated nodes usually mean stale IR or a missing integration.',
+    },
+    'IR-LINT-DUPLICATE-EDGE-006': {
+        title: 'Duplicate from→to edge',
+        remediation: 'Collapse duplicate edges or distinguish them with metadata if your model allows. Parallel duplicates clutter views and can double-count in generators.',
+    },
+    'IR-LINT-HTTP-MISSING-NAME-007': {
+        title: 'HTTP-like node missing display name',
+        remediation: 'Set a short human-readable `name` on the node for docs, OpenAPI titles, and graph labels.',
+    },
+    'IR-LINT-DATASTORE-NO-INCOMING-008': {
+        title: 'Datastore has no incoming edges',
+        remediation: 'Connect a service or data path to this datastore, or remove it if unused. Orphan persistence nodes misrepresent how data is written.',
+    },
+    'IR-LINT-MULTIPLE-HTTP-ENTRIES-009': {
+        title: 'Multiple HTTP entry nodes without incoming edges',
+        remediation: 'Prefer a single API gateway or BFF unless multiple public surfaces are intentional and documented. Multiple entries duplicate auth, rate limits, and observability concerns.',
+    },
+    'IR-LINT-MISSING-AUTH-010': {
+        title: 'HTTP entry missing auth coverage',
+        remediation: 'Add an auth boundary: connect an auth, oauth, jwt, or middleware node with an edge to or from this entry, or set `config.authRequired: false` for intentionally public endpoints (health, assets). Regulated environments expect a documented auth path for every public HTTP entry.',
+    },
+    'IR-LINT-DEAD-NODE-011': {
+        title: 'Non-sink node with incoming edges but no outgoing edges',
+        remediation: 'Add an outgoing edge to a downstream consumer, or remove the node if it is obsolete. Dead-end non-sinks often indicate incomplete migrations or IR mistakes.',
+    },
+    'IR-STRUCT-INVALID_ROOT': {
+        title: 'IR root is not a JSON object',
+        remediation: 'Pass a single JSON object: either `{ "graph": { "nodes": [], "edges": [] } }` or a graph object with a top-level `nodes` array.',
+    },
+    'IR-STRUCT-NO_GRAPH': {
+        title: 'Missing graph shape',
+        remediation: 'Include `.graph` with `nodes` (and optional `edges`) or a top-level `nodes` array so the document describes a graph.',
+    },
+    'IR-STRUCT-NODES_NOT_ARRAY': {
+        title: '`nodes` is not an array',
+        remediation: 'Set `nodes` to an array of node objects, each with a string `id` and a type/kind.',
+    },
+    'IR-STRUCT-EDGES_NOT_ARRAY': {
+        title: '`edges` is present but not an array',
+        remediation: 'Set `edges` to an array of edge objects (or omit `edges` if there are no edges). Malformed `edges` is treated as empty with a warning.',
+    },
+    'IR-STRUCT-EMPTY_GRAPH': {
+        title: 'Graph has no nodes',
+        remediation: 'Add at least one node before validation or export. An empty graph cannot generate a service.',
+    },
+    'IR-STRUCT-NODE_INVALID': {
+        title: 'Node entry is not an object',
+        remediation: 'Each element of `nodes` must be a JSON object with at least `id` and type information.',
+    },
+    'IR-STRUCT-NODE_NO_ID': {
+        title: 'Node missing non-empty id',
+        remediation: 'Assign a stable string `id` to every node. Ids are used for edges and code generation.',
+    },
+    'IR-STRUCT-DUP_NODE_ID': {
+        title: 'Duplicate node id',
+        remediation: 'Ensure node ids are unique. Edges cannot reference duplicate ids unambiguously.',
+    },
+    'IR-STRUCT-NODE_INVALID_CONFIG': {
+        title: 'Node `config` is not a plain object',
+        remediation: 'Use a plain object for `config` (e.g. `{ "url": "/api", "method": "GET" }`). Arrays and null are not valid.',
+    },
+    'IR-STRUCT-HTTP_PATH': {
+        title: 'HTTP endpoint path invalid',
+        remediation: 'Set `config.url` or `config.route` to a non-empty path starting with `/`, e.g. `/users`.',
+    },
+    'IR-STRUCT-HTTP_METHOD': {
+        title: 'HTTP method not supported',
+        remediation: 'Use GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS in `config.method` (default may be applied as POST).',
+    },
+    'IR-STRUCT-EDGE_INVALID': {
+        title: 'Edge is not an object',
+        remediation: 'Each edge must be an object with `from`/`to` (or `source`/`target`) referencing node ids.',
+    },
+    'IR-STRUCT-EDGE_NO_ENDPOINTS': {
+        title: 'Edge missing endpoints',
+        remediation: 'Set both ends of the edge to existing node ids using `from` and `to` (or legacy `source`/`target`).',
+    },
+    'IR-STRUCT-EDGE_AMBIGUOUS_FROM': {
+        title: 'Edge references duplicate source id',
+        remediation: 'Resolve duplicate node ids first; edges cannot point to an ambiguous source.',
+    },
+    'IR-STRUCT-EDGE_UNKNOWN_FROM': {
+        title: 'Edge references unknown source node',
+        remediation: 'Add a node with the referenced id or correct the `from` endpoint.',
+    },
+    'IR-STRUCT-EDGE_AMBIGUOUS_TO': {
+        title: 'Edge references duplicate target id',
+        remediation: 'Resolve duplicate node ids first; edges cannot point to an ambiguous target.',
+    },
+    'IR-STRUCT-EDGE_UNKNOWN_TO': {
+        title: 'Edge references unknown target node',
+        remediation: 'Add a node with the referenced id or correct the `to` endpoint.',
+    },
+    'IR-STRUCT-CYCLE': {
+        title: 'Directed cycle in the graph',
+        remediation: 'Remove or break cyclic edges unless your deployment explicitly allows synchronous loops. Cycles block layering and complicate codegen assumptions.',
+    },
+    'DRIFT-MISSING': {
+        title: 'Exported file missing on disk',
+        remediation: 'Regenerate the export (`archrad export`) or restore the missing file so the tree matches the deterministic output for this IR.',
+    },
+    'DRIFT-MODIFIED': {
+        title: 'File differs from deterministic export',
+        remediation: 'Revert manual edits to generated files or update the IR and re-export so the on-disk tree matches the compiler output.',
+    },
+    'DRIFT-EXTRA': {
+        title: 'Extra file not in deterministic export',
+        remediation: 'Remove stray files from the export directory or add them to the model if they should be generated. Use `--strict-extra` semantics as documented for your CI gate.',
+    },
+    'DRIFT-NO-EXPORT': {
+        title: 'No export produced for drift comparison',
+        remediation: 'Fix IR structural/lint errors blocking export, or verify `--target` and IR content so the exporter emits files.',
+    },
+};
+export function listStaticRuleCodes() {
+    return Object.keys(GUIDANCE).sort();
+}
+export function getStaticRuleGuidance(findingCode) {
+    const g = GUIDANCE[findingCode];
+    if (!g)
+        return null;
+    return {
+        findingCode,
+        title: g.title,
+        remediation: g.remediation,
+        docsUrl: docsUrlForFindingCode(findingCode),
+    };
+}

package/dist/stringEdgeStrip.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Linear-time trimming of repeated edge characters (avoids polynomial ReDoS on
+ * patterns like `/^-+|-+$/` when applied to uncontrolled strings).
+ */
+export declare const MAX_UNTRUSTED_STRING_LEN = 8192;
+export declare function stripLeadingTrailingHyphens(s: string, maxLen?: number): string;
+export declare function stripLeadingTrailingUnderscores(s: string, maxLen?: number): string;
+//# sourceMappingURL=stringEdgeStrip.d.ts.map

package/dist/stringEdgeStrip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stringEdgeStrip.d.ts","sourceRoot":"","sources":["../src/stringEdgeStrip.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,SAA2B,GAAG,MAAM,CAOhG;AAED,wBAAgB,+BAA+B,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,SAA2B,GAAG,MAAM,CAOpG"}

package/dist/stringEdgeStrip.js

@@ -0,0 +1,25 @@
+/**
+ * Linear-time trimming of repeated edge characters (avoids polynomial ReDoS on
+ * patterns like `/^-+|-+$/` when applied to uncontrolled strings).
+ */
+export const MAX_UNTRUSTED_STRING_LEN = 8192;
+export function stripLeadingTrailingHyphens(s, maxLen = MAX_UNTRUSTED_STRING_LEN) {
+    const t = s.length <= maxLen ? s : s.slice(0, maxLen);
+    let i = 0;
+    let j = t.length;
+    while (i < j && t[i] === '-')
+        i++;
+    while (j > i && t[j - 1] === '-')
+        j--;
+    return t.slice(i, j);
+}
+export function stripLeadingTrailingUnderscores(s, maxLen = MAX_UNTRUSTED_STRING_LEN) {
+    const t = s.length <= maxLen ? s : s.slice(0, maxLen);
+    let i = 0;
+    let j = t.length;
+    while (i < j && t[i] === '_')
+        i++;
+    while (j > i && t[j - 1] === '_')
+        j--;
+    return t.slice(i, j);
+}