micro-contracts 0.17.0 → 0.17.2

package/cli-contract.yaml

@@ -650,6 +650,61 @@ command_sets:
           idempotent: true
           side_effects: []
 
+      # ── insights ─────────────────────────────────────
+      insights:
+        summary: Emit ExternalInsight JSON for agent-contracts-analyzer.
+        description: >-
+          Reads x-micro-contracts-depend-on from OpenAPI specs and outputs
+          structured dependency edges and anchor mappings as JSON on stdout.
+          Used by agent-contracts-analyzer CommandProvider integration.
+        usage:
+          - micro-contracts insights --format json
+          - micro-contracts insights --format json --project-root .
+
+        options:
+          - name: format
+            description: Output format (json only).
+            value_name: format
+            schema:
+              type: string
+              default: json
+
+          - name: project-root
+            description: Project root directory containing micro-contracts.config.yaml.
+            value_name: path
+            schema:
+              type: string
+              default: .
+
+          - name: config
+            aliases: [c]
+            description: Path to config file (micro-contracts.config.yaml).
+            value_name: path
+            schema:
+              type: string
+            file:
+              mode: read
+              exists: false
+              media_type: application/yaml
+              encoding: utf-8
+
+        exits:
+          '0':
+            description: ExternalInsight JSON written to stdout.
+            stdout:
+              format: json
+
+          '1':
+            description: Insights generation failed.
+            stderr:
+              format: text
+
+        x-agent:
+          risk_level: low
+          requires_confirmation: false
+          idempotent: true
+          side_effects: []
+
       # ── guardrails-init ──────────────────────────────
       guardrails-init:
         path: [guardrails-init]

package/dist/external/insight-provider.d.ts

@@ -0,0 +1,16 @@
+/**
+ * External Insight Provider for agent-contracts-analyzer (Issue #24).
+ * Exposes x-micro-contracts-depend-on as ExternalInsight edges and anchor mappings.
+ */
+import type { ExternalInsight, InsightProvider, InsightQuery } from "agent-contracts-analyzer";
+export declare const MICRO_CONTRACTS_INSIGHT_SOURCE = "micro-contracts";
+export interface BuildInsightOptions {
+    configPath?: string;
+}
+export declare function buildExternalInsight(projectRoot: string, options?: BuildInsightOptions): ExternalInsight;
+export declare class MicroContractsInsightProvider implements InsightProvider {
+    readonly name = "micro-contracts";
+    provide(query: InsightQuery): Promise<ExternalInsight>;
+}
+export declare const microContractsInsightProvider: MicroContractsInsightProvider;
+//# sourceMappingURL=insight-provider.d.ts.map

package/dist/external/insight-provider.js

@@ -0,0 +1,241 @@
+/**
+ * External Insight Provider for agent-contracts-analyzer (Issue #24).
+ * Exposes x-micro-contracts-depend-on as ExternalInsight edges and anchor mappings.
+ */
+import fs from "fs";
+import path from "path";
+import { createRequire } from "module";
+import { loadConfig, loadOpenAPISpec } from "../generator/index.js";
+import { extractDependencies } from "../types.js";
+import { isMultiModuleConfig, resolveModuleConfig } from "../types.js";
+const require = createRequire(import.meta.url);
+const pkg = require("../../package.json");
+export const MICRO_CONTRACTS_INSIGHT_SOURCE = "micro-contracts";
+const EVIDENCE_KIND = "api_contract_declaration";
+const EDGE_WEIGHT = 0.9;
+function findConfigFile(projectRoot) {
+    const candidates = [
+        "micro-contracts.config.yaml",
+        "micro-contracts.config.yml",
+        "api-framework.config.yaml",
+        "api-framework.config.yml",
+    ];
+    for (const candidate of candidates) {
+        const configPath = path.join(projectRoot, candidate);
+        if (fs.existsSync(configPath))
+            return configPath;
+    }
+    return null;
+}
+function toProjectRelative(projectRoot, absolutePath) {
+    const rel = path.relative(projectRoot, absolutePath);
+    return rel.startsWith("..") ? absolutePath : rel.split(path.sep).join("/");
+}
+function dependencyDomainId(dep) {
+    return dep.raw;
+}
+function serviceApiSymbolId(contractOutputRel, service, method) {
+    return `${contractOutputRel}/services/${service}ServiceApi.ts#${method}`;
+}
+function findDeclarationLine(fileContent, needle) {
+    const lines = fileContent.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(needle)) {
+            return i + 1;
+        }
+    }
+    return undefined;
+}
+function buildEvidence(detail, openapiRel, openapiContent, needle, symbolId) {
+    const line = needle ? findDeclarationLine(openapiContent, needle) : undefined;
+    return {
+        kind: EVIDENCE_KIND,
+        detail,
+        filePath: openapiRel,
+        ...(line !== undefined ? { line } : {}),
+        ...(symbolId !== undefined ? { symbolId } : {}),
+    };
+}
+function collectOperationIndex(spec) {
+    const index = new Map();
+    const httpMethods = ["get", "post", "put", "patch", "delete"];
+    for (const pathItem of Object.values(spec.paths)) {
+        for (const httpMethod of httpMethods) {
+            const operation = pathItem[httpMethod];
+            if (!operation?.operationId)
+                continue;
+            const service = operation["x-micro-contracts-service"];
+            const method = operation["x-micro-contracts-method"];
+            if (typeof service === "string" && typeof method === "string") {
+                index.set(operation.operationId, { service, method });
+            }
+        }
+    }
+    return index;
+}
+function operationDomainId(moduleName, service, method) {
+    return `${moduleName}.${service}.${method}`;
+}
+function edgeKey(from, to, kind) {
+    return `${from}\0${to}\0${kind}`;
+}
+function buildApiRefSymbolAnchor(contractOutputRel, dep) {
+    const symbolId = serviceApiSymbolId(contractOutputRel, dep.service, dep.method);
+    return {
+        symbolId,
+        filePath: `${contractOutputRel}/services/${dep.service}ServiceApi.ts`,
+        startLine: 1,
+        endLine: 1,
+    };
+}
+export function buildExternalInsight(projectRoot, options = {}) {
+    const resolvedRoot = path.resolve(projectRoot);
+    const configPath = options.configPath
+        ? path.resolve(options.configPath)
+        : findConfigFile(resolvedRoot);
+    if (!configPath) {
+        throw new Error("micro-contracts.config.yaml not found. Run from project root or pass --config.");
+    }
+    const config = loadConfig(configPath);
+    if (!isMultiModuleConfig(config)) {
+        throw new Error("Insight provider requires multi-module config with modules.");
+    }
+    const configDir = path.dirname(configPath);
+    const defaults = config.defaults ?? {};
+    const moduleContexts = [];
+    const contractOutputByModule = new Map();
+    for (const [moduleName, moduleConfig] of Object.entries(config.modules)) {
+        const resolved = resolveModuleConfig(moduleName, moduleConfig, defaults);
+        const openapiAbs = path.resolve(configDir, resolved.openapi);
+        if (!fs.existsSync(openapiAbs)) {
+            continue;
+        }
+        const spec = loadOpenAPISpec(openapiAbs);
+        const openapiRel = toProjectRelative(resolvedRoot, openapiAbs);
+        const contractRel = toProjectRelative(resolvedRoot, path.resolve(resolvedRoot, resolved.contractOutput));
+        contractOutputByModule.set(moduleName, contractRel);
+        moduleContexts.push({
+            name: moduleName,
+            openapiRel,
+            resolved,
+            spec,
+        });
+    }
+    const edges = [];
+    const edgeSeen = new Set();
+    const anchorByDomain = new Map();
+    const ensureModuleAnchor = (ctx) => {
+        if (anchorByDomain.has(ctx.name))
+            return;
+        anchorByDomain.set(ctx.name, {
+            domainId: ctx.name,
+            filePaths: [ctx.openapiRel, ctx.resolved.contractOutput],
+        });
+    };
+    const ensureApiRefAnchor = (dep) => {
+        const domainId = dependencyDomainId(dep);
+        if (anchorByDomain.has(domainId))
+            return;
+        const contractRel = contractOutputByModule.get(dep.module);
+        if (!contractRel)
+            return;
+        const targetOpenapi = moduleContexts.find((m) => m.name === dep.module);
+        const filePaths = targetOpenapi
+            ? [targetOpenapi.openapiRel, contractRel]
+            : [contractRel];
+        anchorByDomain.set(domainId, {
+            domainId,
+            filePaths,
+            symbolIds: [serviceApiSymbolId(contractRel, dep.service, dep.method)],
+            symbols: [buildApiRefSymbolAnchor(contractRel, dep)],
+        });
+    };
+    const ensureOperationAnchor = (moduleName, service, method, contractRel, openapiRel) => {
+        const domainId = operationDomainId(moduleName, service, method);
+        if (anchorByDomain.has(domainId))
+            return;
+        const symbolId = serviceApiSymbolId(contractRel, service, method);
+        anchorByDomain.set(domainId, {
+            domainId,
+            filePaths: [openapiRel, contractRel],
+            symbolIds: [symbolId],
+            symbols: [
+                {
+                    symbolId,
+                    filePath: `${contractRel}/services/${service}ServiceApi.ts`,
+                    startLine: 1,
+                    endLine: 1,
+                },
+            ],
+        });
+    };
+    for (const ctx of moduleContexts) {
+        ensureModuleAnchor(ctx);
+        const openapiContent = fs.readFileSync(path.resolve(resolvedRoot, ctx.openapiRel), "utf-8");
+        const deps = extractDependencies(ctx.spec);
+        const contractRel = contractOutputByModule.get(ctx.name);
+        const opIndex = collectOperationIndex(ctx.spec);
+        for (const dep of deps.moduleLevelDeps) {
+            const from = ctx.name;
+            const to = dependencyDomainId(dep);
+            const kind = "api_dependency";
+            const key = edgeKey(from, to, kind);
+            if (edgeSeen.has(key))
+                continue;
+            edgeSeen.add(key);
+            ensureApiRefAnchor(dep);
+            edges.push({
+                from,
+                to,
+                kind,
+                propagation: "forward",
+                weight: EDGE_WEIGHT,
+                evidence: [
+                    buildEvidence(`module declares dependency on ${dep.raw}`, ctx.openapiRel, openapiContent, dep.raw),
+                ],
+            });
+        }
+        for (const [operationId, opDeps] of deps.operationLevelDeps) {
+            const opMeta = opIndex.get(operationId);
+            if (!opMeta)
+                continue;
+            const from = operationDomainId(ctx.name, opMeta.service, opMeta.method);
+            ensureOperationAnchor(ctx.name, opMeta.service, opMeta.method, contractRel, ctx.openapiRel);
+            for (const dep of opDeps) {
+                const to = dependencyDomainId(dep);
+                const kind = "api_operation_dependency";
+                const key = edgeKey(from, to, kind);
+                if (edgeSeen.has(key))
+                    continue;
+                edgeSeen.add(key);
+                ensureApiRefAnchor(dep);
+                const fromSymbolId = serviceApiSymbolId(contractRel, opMeta.service, opMeta.method);
+                edges.push({
+                    from,
+                    to,
+                    kind,
+                    propagation: "forward",
+                    weight: EDGE_WEIGHT,
+                    evidence: [
+                        buildEvidence(`operation ${from} declares dependency on ${dep.raw}`, ctx.openapiRel, openapiContent, dep.raw, fromSymbolId),
+                    ],
+                });
+            }
+        }
+    }
+    return {
+        source: MICRO_CONTRACTS_INSIGHT_SOURCE,
+        sourceVersion: pkg.version,
+        generatedAt: new Date().toISOString(),
+        edges,
+        anchorMapping: [...anchorByDomain.values()],
+    };
+}
+export class MicroContractsInsightProvider {
+    name = MICRO_CONTRACTS_INSIGHT_SOURCE;
+    async provide(query) {
+        return buildExternalInsight(query.projectRoot);
+    }
+}
+export const microContractsInsightProvider = new MicroContractsInsightProvider();
+//# sourceMappingURL=insight-provider.js.map