@agentlighthouse/core 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentLighthouse contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @agentlighthouse/core
+
+Core scanner, schemas, scoring, comparison, and reporters for AgentLighthouse.
+
+This package is intended for tool authors who want to embed AgentLighthouse's local-first agent-readiness analysis. The public alpha API is intentionally centered on the root export:
+
+```ts
+import {
+  scanProject,
+  compareScanResults,
+  renderMarkdownReport,
+  renderSarifReport
+} from "@agentlighthouse/core";
+```
+
+The API is alpha. See `docs/SCHEMA_STABILITY.md` in the repository before depending on report schemas or finding fingerprints.

package/dist/analyzers/mcp.d.ts

@@ -0,0 +1,8 @@
+import type { Finding, McpAnalysis, ProjectSignals } from "../schemas/types.js";
+interface McpAnalyzerResult {
+    analysis: McpAnalysis;
+    findings: Finding[];
+}
+export declare function analyzeMcp(signals: ProjectSignals): McpAnalyzerResult;
+export {};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/analyzers/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/analyzers/mcp.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAmB,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAkCjG,UAAU,iBAAiB;IACzB,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,iBAAiB,CAsIrE"}

package/dist/analyzers/mcp.js

@@ -0,0 +1,214 @@
+import { finding } from "../findings/helpers.js";
+const ambiguousNames = new Set([
+    "run",
+    "query",
+    "create",
+    "update",
+    "delete",
+    "tool",
+    "call",
+    "exec"
+]);
+const destructiveWords = [
+    "delete",
+    "remove",
+    "write",
+    "update",
+    "create",
+    "drop",
+    "truncate",
+    "revoke"
+];
+const privacyWords = [
+    "secret",
+    "token",
+    "auth",
+    "private",
+    "user",
+    "email",
+    "database",
+    "filesystem",
+    "network"
+];
+export function analyzeMcp(signals) {
+    const files = detectMcpFiles(signals);
+    const tools = files.flatMap((file) => extractTools(file, signals.textByPath[file] ?? ""));
+    const ambiguousTools = tools.filter((tool) => ambiguousNames.has(tool.name.toLowerCase()));
+    const destructiveTools = tools.filter((tool) => tool.destructive);
+    const privacySensitiveTools = tools.filter((tool) => tool.privacySensitive);
+    const weakTools = tools.filter((tool) => tool.weak);
+    const findings = [];
+    if (files.length > 0 && tools.length === 0) {
+        findings.push(finding({
+            id: "MCP_TOOL_DEFINITIONS_NOT_PARSED",
+            title: "MCP project detected but tool definitions were not parsed",
+            severity: "medium",
+            category: "mcp_tools",
+            description: "MCP files or dependencies were detected, but static analysis could not find clear tool registrations.",
+            evidence: files.slice(0, 8),
+            recommendation: "Use explicit registerTool/server.tool definitions with names, descriptions, schemas, and examples.",
+            agentFailureMode: "A coding agent may know the project exposes MCP but be unable to infer which tools exist or when to use them.",
+            fixExample: "Register tools with specific names and descriptions, for example registerTool('list_workspace_documents', { description, inputSchema }).",
+            suggestedFixType: "update_file"
+        }));
+    }
+    pushToolFinding(findings, {
+        id: "MCP_TOOL_NAME_AMBIGUOUS",
+        title: "MCP tool names are ambiguous",
+        severity: "medium",
+        tools: ambiguousTools,
+        recommendation: "Rename generic tools so the action and resource are obvious.",
+        agentFailureMode: "A coding agent may choose a generic tool like run or query for the wrong workflow.",
+        fixExample: "Use names such as search_docs, create_workspace_ticket, or revoke_api_key."
+    });
+    pushToolFinding(findings, {
+        id: "MCP_TOOL_DESCRIPTION_MISSING",
+        title: "MCP tools are missing descriptions",
+        severity: "high",
+        tools: tools.filter((tool) => !tool.description),
+        recommendation: "Add a description explaining when to use the tool and when not to use it.",
+        agentFailureMode: "A coding agent may call a tool from its name alone and miss preconditions or side effects.",
+        fixExample: "Description: 'Search public docs by keyword. Do not use for private customer data.'"
+    });
+    pushToolFinding(findings, {
+        id: "MCP_TOOL_DESCRIPTION_SHALLOW",
+        title: "MCP tool descriptions are too shallow",
+        severity: "medium",
+        tools: tools.filter((tool) => tool.description && tool.description.length < 40),
+        recommendation: "Expand tool descriptions with intent, constraints, and safe usage guidance.",
+        agentFailureMode: "A coding agent may not distinguish similar tools without usage context.",
+        fixExample: "Mention input expectations, side effects, auth requirements, and error behavior."
+    });
+    pushToolFinding(findings, {
+        id: "MCP_TOOL_INPUT_SCHEMA_MISSING",
+        title: "MCP tools are missing input schemas",
+        severity: "high",
+        tools: tools.filter((tool) => !tool.hasInputSchema),
+        recommendation: "Add structured input schemas with required fields and descriptions.",
+        agentFailureMode: "A coding agent may pass malformed arguments or omit required identifiers.",
+        fixExample: "Use a zod/object schema with workspace_id and query fields plus descriptions."
+    });
+    pushToolFinding(findings, {
+        id: "MCP_TOOL_EXAMPLE_MISSING",
+        title: "MCP tools lack examples or usage notes",
+        severity: "low",
+        tools: tools.filter((tool) => !tool.hasExamples),
+        recommendation: "Add examples or usage notes for common calls.",
+        agentFailureMode: "A coding agent may not know the expected argument shape or output semantics.",
+        fixExample: "Include an example invocation showing realistic placeholder arguments."
+    });
+    pushToolFinding(findings, {
+        id: "MCP_TOOL_DESTRUCTIVE_ACTION_UNMARKED",
+        title: "Destructive MCP tools are not clearly marked",
+        severity: "high",
+        tools: destructiveTools.filter((tool) => !/danger|destructive|irreversible|confirm|permission/i.test(tool.description ?? "")),
+        recommendation: "Mark destructive tools and document confirmation, permissions, and safe testing behavior.",
+        agentFailureMode: "A coding agent may call a write/delete tool without realizing it changes external state.",
+        fixExample: "State that the tool mutates data and requires explicit user approval outside test fixtures."
+    });
+    pushToolFinding(findings, {
+        id: "MCP_TOOL_AUTH_PRIVACY_UNCLEAR",
+        title: "Privacy-sensitive MCP tools lack auth/privacy guidance",
+        severity: "medium",
+        tools: privacySensitiveTools.filter((tool) => !/auth|permission|private|secret|token|privacy/i.test(tool.description ?? "")),
+        recommendation: "Document credentials, permissions, and private-data handling for sensitive tools.",
+        agentFailureMode: "A coding agent may expose private data or call a tool without required auth context.",
+        fixExample: "Mention required token scopes and whether arguments or outputs may contain private data."
+    });
+    pushToolFinding(findings, {
+        id: "MCP_TOOL_ERROR_BEHAVIOR_UNCLEAR",
+        title: "MCP tool error behavior is unclear",
+        severity: "low",
+        tools: tools.filter((tool) => !/error|fail|not found|unauthorized|retry/i.test(tool.description ?? "")),
+        recommendation: "Explain common errors and whether retry or user follow-up is appropriate.",
+        agentFailureMode: "A coding agent may retry unsafe operations or fail silently when a tool returns an error.",
+        fixExample: "Document not-found, unauthorized, rate-limit, and validation failures."
+    });
+    return {
+        analysis: {
+            detected: files.length > 0,
+            files,
+            toolCount: tools.length,
+            toolsWithSchemas: tools.filter((tool) => tool.hasInputSchema).length,
+            toolsWithExamples: tools.filter((tool) => tool.hasExamples).length,
+            ambiguousTools: ambiguousTools.map((tool) => `${tool.file}: ${tool.name}`),
+            destructiveTools: destructiveTools.map((tool) => `${tool.file}: ${tool.name}`),
+            privacySensitiveTools: privacySensitiveTools.map((tool) => `${tool.file}: ${tool.name}`),
+            weakTools: weakTools.map((tool) => `${tool.file}: ${tool.name}`)
+        },
+        findings
+    };
+}
+function detectMcpFiles(signals) {
+    const dependencies = new Set([
+        ...(signals.packageJson?.dependencies ?? []),
+        ...(signals.packageJson?.devDependencies ?? [])
+    ]);
+    const hasMcpPackage = [...dependencies].some((dependency) => /modelcontextprotocol|mcp/i.test(dependency));
+    const patternFiles = Object.entries(signals.textByPath)
+        .filter(([file, content]) => hasMcpPackage &&
+        !file.startsWith("docs/") &&
+        /registerTool|server\.tool|new McpServer|@modelcontextprotocol/i.test(content))
+        .map(([file]) => file);
+    return [
+        ...new Set([...signals.mcpFiles.filter((file) => signals.textByPath[file]), ...patternFiles])
+    ].sort();
+}
+function extractTools(file, content) {
+    const tools = [];
+    const registrationPattern = /(?:registerTool|server\.tool|\.tool)\(\s*["'`]([^"'`]+)["'`]\s*,\s*\{([\s\S]*?)\n\}\s*\);/g;
+    for (const match of content.matchAll(registrationPattern)) {
+        const name = match[1] ?? "unknown_tool";
+        const block = match[2] ?? "";
+        const description = extractDescription(block);
+        const haystack = `${name} ${description ?? ""} ${block}`.toLowerCase();
+        const destructive = destructiveWords.some((word) => haystack.includes(word));
+        const privacySensitive = privacyWords.some((word) => haystack.includes(word));
+        const hasInputSchema = /inputSchema|schema|z\.object|properties\s*:|required\s*:/i.test(block);
+        const hasExamples = /example|usage|sample/i.test(block);
+        const riskReasons = [
+            ambiguousNames.has(name.toLowerCase()) ? "ambiguous name" : undefined,
+            !description ? "missing description" : undefined,
+            description && description.length < 40 ? "shallow description" : undefined,
+            !hasInputSchema ? "missing input schema" : undefined,
+            destructive ? "destructive or mutating behavior" : undefined,
+            privacySensitive ? "privacy/auth sensitive behavior" : undefined
+        ].filter((reason) => Boolean(reason));
+        tools.push({
+            name,
+            file,
+            description,
+            hasInputSchema,
+            hasExamples,
+            destructive,
+            privacySensitive,
+            weak: riskReasons.length > 0,
+            riskReasons
+        });
+    }
+    return tools;
+}
+function extractDescription(block) {
+    const propertyMatch = block.match(/description\s*:\s*["'`]([^"'`]+)["'`]/i);
+    if (propertyMatch?.[1])
+        return propertyMatch[1];
+    const stringArgument = block.match(/^\s*["'`]([^"'`]+)["'`]/);
+    return stringArgument?.[1];
+}
+function pushToolFinding(findings, input) {
+    if (input.tools.length === 0)
+        return;
+    findings.push(finding({
+        id: input.id,
+        title: input.title,
+        severity: input.severity,
+        category: "mcp_tools",
+        description: `${input.tools.length} MCP tool(s) need stronger agent-facing metadata.`,
+        evidence: input.tools.slice(0, 8).map((tool) => `${tool.file}: ${tool.name}`),
+        recommendation: input.recommendation,
+        agentFailureMode: input.agentFailureMode,
+        fixExample: input.fixExample,
+        affectedFile: input.tools[0]?.file,
+        suggestedFixType: "update_file"
+    }));
+}

package/dist/analyzers/openapi.d.ts

@@ -0,0 +1,7 @@
+import type { ApiAnalysis, Finding, ProjectSignals } from "../schemas/types.js";
+export interface OpenApiAnalyzerResult {
+    analysis: ApiAnalysis;
+    findings: Finding[];
+}
+export declare function analyzeOpenApi(signals: ProjectSignals): OpenApiAnalyzerResult;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/analyzers/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/analyzers/openapi.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA0BhF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,qBAAqB,CAyC7E"}

package/dist/analyzers/openapi.js

@@ -0,0 +1,344 @@
+import { parse as parseYaml } from "yaml";
+import { finding } from "../findings/helpers.js";
+const httpMethods = new Set(["get", "post", "put", "patch", "delete"]);
+const errorStatusCodes = ["400", "401", "403", "404", "409", "429", "500"];
+const destructiveWords = ["delete", "cancel", "refund", "revoke", "close", "remove"];
+const genericOperationNames = new Set([
+    "get",
+    "list",
+    "create",
+    "update",
+    "delete",
+    "run",
+    "query",
+    "execute",
+    "submit"
+]);
+export function analyzeOpenApi(signals) {
+    const specs = signals.openApiFiles
+        .map((file) => ({ file, spec: parseSpec(signals.textByPath[file]) }))
+        .filter((entry) => Boolean(entry.spec));
+    const operations = specs.flatMap(({ file, spec }) => collectOperations(file, spec));
+    const authSchemes = specs.flatMap(({ spec }) => securitySchemes(spec));
+    const operationLabels = operations.map(labelOperation);
+    const destructiveOperations = operations.filter(isDestructiveOperation).map(labelOperation);
+    const operationsWithExamples = operations.filter((operation) => hasRequestExample(operation.operation) || hasResponseExample(operation.operation)).length;
+    const operationsMissingDescriptions = operations.filter(({ operation }) => weakText(stringValue(operation.description), 32)).length;
+    const weakOperations = operations.filter(isWeakOperation).map(labelOperation);
+    const highRiskOperations = operations
+        .filter((operation) => isDestructiveOperation(operation) || !hasErrorResponses(operation.operation))
+        .map(labelOperation);
+    const findings = [];
+    findings.push(...specLevelFindings(specs));
+    findings.push(...operationQualityFindings(operations));
+    return {
+        analysis: {
+            specFiles: specs.map((entry) => entry.file),
+            operationCount: operations.length,
+            operationsWithExamples,
+            operationsMissingDescriptions,
+            destructiveOperations,
+            authSchemes,
+            weakOperations: weakOperations.slice(0, 20),
+            highRiskOperations: highRiskOperations.slice(0, 20)
+        },
+        findings: operationLabels.length === 0 && specs.length > 0
+            ? [...findings, noOperationsFinding(specs[0]?.file)]
+            : findings
+    };
+}
+function parseSpec(content) {
+    if (!content)
+        return undefined;
+    try {
+        const parsed = content.trim().startsWith("{")
+            ? JSON.parse(content)
+            : parseYaml(content);
+        return asObject(parsed);
+    }
+    catch {
+        return undefined;
+    }
+}
+function collectOperations(file, spec) {
+    const paths = asObject(spec.paths);
+    if (!paths)
+        return [];
+    const operations = [];
+    for (const [apiPath, pathItem] of Object.entries(paths)) {
+        const pathObject = asObject(pathItem);
+        if (!pathObject)
+            continue;
+        for (const [method, operation] of Object.entries(pathObject)) {
+            if (!httpMethods.has(method.toLowerCase()))
+                continue;
+            const operationObject = asObject(operation);
+            if (!operationObject)
+                continue;
+            operations.push({
+                file,
+                method: method.toUpperCase(),
+                path: apiPath,
+                operation: operationObject
+            });
+        }
+    }
+    return operations;
+}
+function specLevelFindings(specs) {
+    const findings = [];
+    for (const { file, spec } of specs) {
+        const info = asObject(spec.info);
+        const description = stringValue(info?.description);
+        const authSchemes = securitySchemes(spec);
+        const fullText = JSON.stringify(spec).toLowerCase();
+        if (weakText(description, 40)) {
+            findings.push(finding({
+                id: "OPENAPI_WEAK_SPEC_DESCRIPTION",
+                title: "OpenAPI spec description is too thin for agents",
+                severity: "medium",
+                category: "api_schema",
+                description: "The API-level description does not explain product concepts, auth expectations, or common workflows.",
+                evidence: [`${file}: info.description is missing or shorter than 40 characters.`],
+                recommendation: "Add a concise overview of the API domain, common workflows, auth model, and safe usage constraints.",
+                agentFailureMode: "A coding agent may jump straight to endpoints without understanding product nouns, authentication, or workflow ordering.",
+                fixExample: "Describe the main resources, required authentication, common create/list/update flows, and where to find examples.",
+                affectedFile: file,
+                suggestedFixType: "update_file"
+            }));
+        }
+        if (authSchemes.length === 0 &&
+            !/(api key|bearer|oauth|authorization|authentication)/i.test(fullText)) {
+            findings.push(finding({
+                id: "OPENAPI_AUTH_UNCLEAR",
+                title: "OpenAPI authentication is unclear",
+                severity: "high",
+                category: "api_schema",
+                description: "No security scheme or clear authentication guidance was detected.",
+                evidence: [
+                    `${file}: components.securitySchemes is missing and auth hints were not found.`
+                ],
+                recommendation: "Document the auth scheme, required headers, scopes, and placeholder-safe example credentials.",
+                agentFailureMode: "A coding agent may generate client code without the required Authorization header or may invent unsafe credential handling.",
+                fixExample: "Add an HTTP bearer or API key security scheme and a request example using EXAMPLE_API_KEY.",
+                affectedFile: file,
+                suggestedFixType: "update_file"
+            }));
+        }
+        if (!Array.isArray(spec.servers) && !stringValue(spec.host)) {
+            findings.push(finding({
+                id: "OPENAPI_SERVER_URL_MISSING",
+                title: "OpenAPI server URL is missing",
+                severity: "low",
+                category: "api_schema",
+                description: "Agents need a base URL signal to generate usable client examples.",
+                evidence: [`${file}: servers is missing.`],
+                recommendation: "Add production and sandbox server URLs, or explain how agents should configure the base URL.",
+                agentFailureMode: "A coding agent may invent a base URL or hardcode the wrong host.",
+                fixExample: "Add servers: [{ url: 'https://api.example.com/v1' }].",
+                affectedFile: file,
+                suggestedFixType: "update_file"
+            }));
+        }
+    }
+    return findings;
+}
+function operationQualityFindings(operations) {
+    const findings = [];
+    const missingOperationIds = operations.filter((operation) => weakOperationId(operation.operation));
+    const weakDescriptions = operations.filter(({ operation }) => weakText(stringValue(operation.description), 32));
+    const missingRequestExamples = operations.filter((operation) => ["POST", "PUT", "PATCH"].includes(operation.method) && !hasRequestExample(operation.operation));
+    const missingResponseExamples = operations.filter((operation) => !hasResponseExample(operation.operation));
+    const missingErrorResponses = operations.filter((operation) => !hasErrorResponses(operation.operation));
+    const ambiguousNames = operations.filter((operation) => ambiguousOperationName(operation.operation));
+    const unmarkedDestructive = operations.filter((operation) => isDestructiveOperation(operation) && !destructiveOperationMarked(operation.operation));
+    const paginationUnclear = operations.filter((operation) => likelyListOperation(operation) &&
+        !operationMentions(operation.operation, /(page|cursor|limit|offset|next)/i));
+    const rateLimitUnclear = operations.length > 0 &&
+        !operations.some((operation) => operationMentions(operation.operation, /(rate limit|429|too many requests|retry-after)/i));
+    pushAggregate(findings, {
+        id: "OPENAPI_MISSING_OPERATION_ID",
+        title: "OpenAPI operations have weak or missing operationIds",
+        severity: "medium",
+        records: missingOperationIds,
+        recommendation: "Give every operation a stable, specific operationId such as createWorkspaceInvite or listCustomerInvoices.",
+        agentFailureMode: "A coding agent may generate confusing client methods or call the wrong endpoint when operation IDs are missing or generic.",
+        fixExample: "Use verb+noun names that distinguish similar operations, for example revokeApiKey instead of delete."
+    });
+    pushAggregate(findings, {
+        id: "OPENAPI_WEAK_OPERATION_DESCRIPTION",
+        title: "OpenAPI operations have weak descriptions",
+        severity: "medium",
+        records: weakDescriptions,
+        recommendation: "Add operation descriptions explaining when to use the endpoint, required context, side effects, and recovery behavior.",
+        agentFailureMode: "A coding agent may choose the wrong operation because summaries alone do not explain intent or preconditions.",
+        fixExample: "Add descriptions that mention required IDs, auth scope, side effects, and common failure handling."
+    });
+    pushAggregate(findings, {
+        id: "OPENAPI_MISSING_REQUEST_EXAMPLE",
+        title: "Write operations lack request examples",
+        severity: "medium",
+        records: missingRequestExamples,
+        recommendation: "Add request examples for create/update operations using realistic placeholder values.",
+        agentFailureMode: "A coding agent may send malformed payloads or omit required fields because no concrete request shape is shown.",
+        fixExample: "Add an example body with workspace_id, customer_id, and idempotency_key where relevant."
+    });
+    pushAggregate(findings, {
+        id: "OPENAPI_MISSING_RESPONSE_EXAMPLE",
+        title: "Operations lack response examples",
+        severity: "low",
+        records: missingResponseExamples,
+        recommendation: "Add response examples for successful and important error cases.",
+        agentFailureMode: "A coding agent may write incorrect parsing code because expected response shapes are not exemplified.",
+        fixExample: "Add 200/201 response examples with IDs, timestamps, pagination cursors, and nested objects."
+    });
+    pushAggregate(findings, {
+        id: "OPENAPI_MISSING_ERROR_RESPONSES",
+        title: "Operations lack common error responses",
+        severity: "medium",
+        records: missingErrorResponses,
+        recommendation: "Document likely 400/401/403/404/409/429/500 responses and how callers should recover.",
+        agentFailureMode: "A coding agent may generate happy-path-only integrations with no auth, retry, or validation recovery.",
+        fixExample: "Add 401, 404, 409, and 429 responses with short descriptions and example error payloads."
+    });
+    pushAggregate(findings, {
+        id: "OPENAPI_AMBIGUOUS_OPERATION_NAME",
+        title: "OpenAPI operation names are ambiguous",
+        severity: "low",
+        records: ambiguousNames,
+        recommendation: "Rename generic operationIds so similar endpoints are distinguishable to code generators and agents.",
+        agentFailureMode: "A coding agent may map multiple endpoints to vague client methods such as run, query, or update.",
+        fixExample: "Prefer syncCatalog, searchDocuments, or updateWorkspaceMember over generic names."
+    });
+    pushAggregate(findings, {
+        id: "OPENAPI_DESTRUCTIVE_OPERATION_UNMARKED",
+        title: "Destructive API operations are not clearly marked",
+        severity: "high",
+        records: unmarkedDestructive,
+        recommendation: "Mark destructive operations with permission, confirmation, irreversibility, and recovery guidance.",
+        agentFailureMode: "A coding agent may call a destructive endpoint during testing without understanding consequences.",
+        fixExample: "State whether delete/cancel/revoke is irreversible and include sandbox-safe examples."
+    });
+    pushAggregate(findings, {
+        id: "OPENAPI_PAGINATION_UNCLEAR",
+        title: "List operations do not explain pagination",
+        severity: "low",
+        records: paginationUnclear,
+        recommendation: "Document pagination parameters, cursors, limits, and response fields.",
+        agentFailureMode: "A coding agent may fetch only the first page or invent unsupported pagination parameters.",
+        fixExample: "Describe limit and cursor parameters and include a response example with next_cursor."
+    });
+    if (rateLimitUnclear) {
+        findings.push(finding({
+            id: "OPENAPI_RATE_LIMIT_UNCLEAR",
+            title: "OpenAPI rate-limit behavior is unclear",
+            severity: "low",
+            category: "api_schema",
+            description: "No 429, Retry-After, or rate-limit guidance was detected.",
+            evidence: ["No operation mentions 429, Retry-After, or rate limits."],
+            recommendation: "Document rate limits and retry behavior for generated clients.",
+            agentFailureMode: "A coding agent may create brittle retry loops or ignore throttling responses.",
+            fixExample: "Add a 429 response with Retry-After guidance and an example error payload.",
+            suggestedFixType: "update_file"
+        }));
+    }
+    return findings;
+}
+function pushAggregate(findings, input) {
+    if (input.records.length === 0)
+        return;
+    findings.push(finding({
+        id: input.id,
+        title: input.title,
+        severity: input.severity,
+        category: "api_schema",
+        description: `${input.records.length} operation(s) need stronger agent-facing API documentation.`,
+        evidence: input.records.slice(0, 8).map(labelOperation),
+        recommendation: input.recommendation,
+        agentFailureMode: input.agentFailureMode,
+        fixExample: input.fixExample,
+        affectedFile: input.records[0]?.file,
+        suggestedFixType: "update_file"
+    }));
+}
+function noOperationsFinding(file) {
+    return finding({
+        id: "OPENAPI_NO_OPERATIONS",
+        title: "OpenAPI spec has no analyzable operations",
+        severity: "high",
+        category: "api_schema",
+        description: "The spec was detected but no HTTP path operations could be parsed.",
+        evidence: [file ?? "OpenAPI file detected."],
+        recommendation: "Add OpenAPI path operations or fix the spec structure so tools can parse it.",
+        agentFailureMode: "A coding agent cannot discover API workflows from a spec without operations.",
+        fixExample: "Add paths with get/post/patch/delete operations and operationIds.",
+        affectedFile: file,
+        suggestedFixType: "update_file"
+    });
+}
+function securitySchemes(spec) {
+    const components = asObject(spec.components);
+    const schemes = asObject(components?.securitySchemes);
+    return schemes ? Object.keys(schemes) : [];
+}
+function weakOperationId(operation) {
+    const operationId = stringValue(operation.operationId);
+    return (!operationId || operationId.length < 5 || genericOperationNames.has(operationId.toLowerCase()));
+}
+function ambiguousOperationName(operation) {
+    const operationId = stringValue(operation.operationId);
+    if (!operationId)
+        return false;
+    return genericOperationNames.has(operationId.toLowerCase()) || !/[A-Z_-]/.test(operationId);
+}
+function isWeakOperation(record) {
+    return (weakOperationId(record.operation) ||
+        weakText(stringValue(record.operation.description), 32) ||
+        !hasResponseExample(record.operation) ||
+        !hasErrorResponses(record.operation));
+}
+function isDestructiveOperation(record) {
+    const haystack = `${record.method} ${record.path} ${stringValue(record.operation.operationId)} ${stringValue(record.operation.summary)} ${stringValue(record.operation.description)}`.toLowerCase();
+    return record.method === "DELETE" || destructiveWords.some((word) => haystack.includes(word));
+}
+function destructiveOperationMarked(operation) {
+    return operationMentions(operation, /(irreversible|destructive|permission|confirm|cannot be undone|sandbox|danger)/i);
+}
+function likelyListOperation(record) {
+    const haystack = `${record.method} ${record.path} ${stringValue(record.operation.operationId)} ${stringValue(record.operation.summary)}`.toLowerCase();
+    return record.method === "GET" && /(list|search|\/\{[^}]+\}$)/i.test(haystack);
+}
+function hasRequestExample(operation) {
+    return JSON.stringify(operation.requestBody ?? "")
+        .toLowerCase()
+        .includes("example");
+}
+function hasResponseExample(operation) {
+    return JSON.stringify(operation.responses ?? "")
+        .toLowerCase()
+        .includes("example");
+}
+function hasErrorResponses(operation) {
+    const responses = asObject(operation.responses);
+    if (!responses)
+        return false;
+    return errorStatusCodes.some((code) => Object.prototype.hasOwnProperty.call(responses, code));
+}
+function operationMentions(operation, pattern) {
+    return pattern.test(JSON.stringify(operation));
+}
+function labelOperation(record) {
+    const operationId = stringValue(record.operation.operationId);
+    return `${record.file}: ${record.method} ${record.path}${operationId ? ` (${operationId})` : ""}`;
+}
+function weakText(value, minLength) {
+    return !value || value.trim().length < minLength;
+}
+function asObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}

package/dist/analyzers/readiness.d.ts

@@ -0,0 +1,8 @@
+import type { Analyzer, Finding, ProjectSignals, ScanProfile } from "../schemas/types.js";
+export declare class ReadinessAnalyzer implements Analyzer {
+    private readonly profile;
+    readonly id = "readiness-analyzer";
+    constructor(profile?: ScanProfile);
+    analyze(signals: ProjectSignals): Finding[];
+}
+//# sourceMappingURL=readiness.d.ts.map

package/dist/analyzers/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../src/analyzers/readiness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAI1F,qBAAa,iBAAkB,YAAW,QAAQ;IAGpC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,EAAE,wBAAwB;gBAEN,OAAO,GAAE,WAAuB;IAE7D,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,EAAE;CAa5C"}