autotel-cli 0.19.1 → 0.21.0

package/README.md

@@ -201,6 +201,9 @@ npx autotel-cli map --min-score 70
 
 # Fail CI when a check that used to pass now fails
 npx autotel-cli map --baseline git:origin/main
+
+# Annotate the pull request diff in GitHub Actions
+npx autotel-cli map --format github --baseline git:origin/main --no-write
 ```
 
 **Detected frameworks:** `next`, `nitro` (Nuxt), `tanstack-start`, `sveltekit`, `hono`, `express`, `fastify`, `elysia`, `cloudflare`. Override with `--framework <name>`.
@@ -242,7 +245,17 @@ costs no score and is never counted as coverage;
 - `--min-score <n>` - Exit 1 when the global score is below this threshold
 - `--baseline [source]` - Compare against a committed map (path, or `git:<ref>`); exit 1 on regression
 - `--no-write` - Skip writing `autotel.map.json`
-- `--json` / `--output-file <path>` - Machine-readable output
+- `--json` / `--output-file <path>` - Machine-readable output (`--json` is the same as `--format json`)
+- `--format github` - GitHub Actions [workflow annotations](https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions) on stdout; the report goes to stderr and the exit code is unchanged
+- `--limit <n>` - Most annotations `--format github` emits (default 10, how many GitHub keeps per step)
+
+**Annotating pull requests:** with `--baseline`, `--format github` emits the regressions as errors: the checks this pull request broke, nothing already on the map. Without one, it emits the "Fix these first" list, worst entry point first, as warnings. The first line carries the score, as an error when `--min-score` or the baseline failed the run, and says how many findings `--limit` left out. Paths are rebased on `GITHUB_WORKSPACE`, so a package scanned with `--cwd` inside a monorepo still annotates the right file.
+
+```
+::warning file=src/index.ts,line=6,title=autotel map%3A trace::no trace() or span() — this handler is invisible when it breaks
+::warning file=src/index.ts,line=6,title=autotel map%3A audit::no audit trail (money: path says "payment") — withAudit() survives tail sampling
+::notice title=autotel map::score 15/100 (at-risk): 0 instrumented, 0 partial, 3 dark; 6 more findings not shown
+```
 
 ### `autotel codemod trace <path>`
 

package/dist/index.js

@@ -370,9 +370,6 @@ function createCodeFile() {
 		backendImports: [],
 		pluginImports: [],
 		subscriberImports: [],
-		loggerImports: [],
-		loggerSetup: null,
-		loggerExpr: null,
 		autoInstrumentations: [],
 		backendConfig: null,
 		subscribersConfig: [],
@@ -380,23 +377,11 @@ function createCodeFile() {
 	};
 }
 /**
-* Wire Pino as the first-class autotel logger. Adds the import, the
-* `const logger = pino({...})` construction snippet, and sets the
-* `logger:` field on init().
+* Add a name to the autoInstrumentations allowlist. For a logger this is what
+* injects trace context: the app's own logger, created after init(), is
+* patched as it loads, so it is never passed to init().
 */
-function setPinoLogger(file) {
-	file.loggerImports.push({
-		source: "pino",
-		default: "pino"
-	});
-	file.loggerSetup = `const logger = pino({ name: 'app', level: process.env.LOG_LEVEL ?? 'info' });`;
-	file.loggerExpr = "logger";
-}
-/**
-* Add a logger to the autoInstrumentations array. For Winston/Bunyan this
-* enables OpenTelemetry contrib's trace-context injection.
-*/
-function addAutoInstrumentationLogger(file, name) {
+function addAutoInstrumentation(file, name) {
 	if (!file.autoInstrumentations.includes(name)) file.autoInstrumentations.push(name);
 }
 /**
@@ -502,17 +487,7 @@ function renderCodeFile(file) {
 		lines.push(renderImports(file.subscriberImports));
 		lines.push("");
 	}
-	if (file.loggerImports.length > 0) {
-		lines.push(SECTION_MARKER("LOGGER"));
-		lines.push(renderImports(file.loggerImports));
-		lines.push("");
-	}
-	if (file.loggerSetup !== null) {
-		lines.push(file.loggerSetup);
-		lines.push("");
-	}
 	lines.push("init({");
-	if (file.loggerExpr !== null) lines.push(`  logger: ${file.loggerExpr},`);
 	if (file.autoInstrumentations.length > 0) {
 		const list = file.autoInstrumentations.map((n) => `'${n}'`).join(", ");
 		lines.push(`  autoInstrumentations: [${list}],`);
@@ -2240,8 +2215,7 @@ function buildPlanFromDetection(opts) {
 		for (const pkg of p.packages.optional) prod.add(pkg);
 		for (const pkg of p.packages.devOnly) dev.add(pkg);
 	}
-	if (detection.primaryLogger === "pino") prod.add("pino");
-	if (detection.autoInstrumentedDeps.length > 0 || detection.autoInstrumentLoggers.length > 0 || detection.primaryLogger === "winston" || detection.primaryLogger === "bunyan") prod.add("@opentelemetry/auto-instrumentations-node");
+	if (detection.autoInstrumentedDeps.length > 0 || detection.autoInstrumentLoggers.length > 0 || detection.primaryLogger !== null) prod.add("@opentelemetry/auto-instrumentations-node");
 	const envVars = [];
 	const seenEnv = /* @__PURE__ */ new Set();
 	for (const p of presets) for (const ev of [...p.env.required, ...p.env.optional]) {
@@ -2496,7 +2470,7 @@ function renderPlanPreview(plan) {
 		const det = plan.detected;
 		const pkgList = det.packages.map((p) => `${p.name}@${p.version}`).join(", ");
 		lines.push(`${chalk.dim("Detected packages:")} ${pkgList || chalk.dim("(none)")}`);
-		if (det.primaryLogger !== null) lines.push(`${chalk.dim("Logger:")} ${chalk.bold(det.primaryLogger)} ${chalk.dim("(first-class)")}` + (det.autoInstrumentLoggers.length > 0 ? `, ${chalk.dim("+ auto-instrumented:")} ${det.autoInstrumentLoggers.join(", ")}` : ""));
+		if (det.primaryLogger !== null) lines.push(`${chalk.dim("Logger:")} ${chalk.bold(det.primaryLogger)} ${chalk.dim("(auto-instrumented)")}` + (det.autoInstrumentLoggers.length > 0 ? `, ${chalk.dim("+ auto-instrumented:")} ${det.autoInstrumentLoggers.join(", ")}` : ""));
 		if (det.autoInstrumentedDeps.length > 0) lines.push(`${chalk.dim("Covered by auto-instrumentations-node:")} ${det.autoInstrumentedDeps.join(", ")}`);
 		lines.push(`${chalk.dim("Backend:")} ${chalk.bold(det.backend.slug)} ${chalk.dim(`(${det.backend.source}${det.backend.detail ? `: ${det.backend.detail}` : ""})`)}`);
 		if (det.platform !== null) lines.push(`${chalk.dim("Platform:")} ${chalk.bold(det.platform)}`);
@@ -2759,6 +2733,15 @@ function isCI() {
 //#endregion
 //#region src/commands/init.ts
 /**
+* Detected deps whose auto-instrumentation goes by another name. `next` and
+* `fastify` have none in auto-instrumentations-node; http covers them.
+*/
+const DEP_INSTRUMENTATION = {
+	"@aws-sdk/client-s3": ["aws-sdk"],
+	next: [],
+	fastify: []
+};
+/**
 * Run the init command.
 *
 * Order of operations:
@@ -2973,8 +2956,14 @@ function applyPlan(args) {
 		source: "autotel",
 		specifiers: ["init"]
 	});
-	if (plan.detected?.primaryLogger === "pino") setPinoLogger(codeFile);
-	for (const l of plan.detected?.autoInstrumentLoggers ?? []) addAutoInstrumentationLogger(codeFile, l);
+	const detected = plan.detected;
+	const loggers = [...detected?.primaryLogger ? [detected.primaryLogger] : [], ...detected?.autoInstrumentLoggers ?? []];
+	const deps = detected?.autoInstrumentedDeps ?? [];
+	if (loggers.length > 0 || deps.length > 0) for (const name of [
+		"http",
+		...loggers,
+		...deps.flatMap((dep) => DEP_INSTRUMENTATION[dep] ?? [dep])
+	]) addAutoInstrumentation(codeFile, name);
 	for (const preset of presets) {
 		for (const imp of preset.imports) addImport(codeFile, imp, preset.type === "backend" || preset.type === "platform" ? "backend" : preset.type === "plugin" ? "plugin" : preset.type === "subscriber" ? "subscriber" : void 0);
 		if (preset.configBlock.section === "BACKEND_CONFIG") setBackendConfig(codeFile, preset.configBlock.code);
@@ -2999,8 +2988,7 @@ function applyPlan(args) {
 			...codeFile.imports,
 			...codeFile.backendImports,
 			...codeFile.pluginImports,
-			...codeFile.subscriberImports,
-			...codeFile.loggerImports
+			...codeFile.subscriberImports
 		].map((i) => i.source));
 		const addedAuto = diffAutoInstrumentations(parsed, codeFile.autoInstrumentations);
 		const contentChanged = existing !== newContent;
@@ -5671,129 +5659,6 @@ function hasRegressed(comparison) {
 	return comparison.regressions.length > 0 || comparison.delta < 0;
 }
 //#endregion
-//#region src/lib/map/project-facts.ts
-const LLM_PACKAGES = [
-	"openai",
-	"@anthropic-ai/sdk",
-	"ai",
-	"@ai-sdk/openai",
-	"@ai-sdk/anthropic",
-	"@ai-sdk/google",
-	"ai-sdk-ollama",
-	"ollama",
-	"@google/generative-ai",
-	"@mistralai/mistralai",
-	"cohere-ai",
-	"langchain",
-	"@langchain/core"
-];
-const RUNTIME_AUTOTEL_PACKAGES = [
-	"autotel",
-	"autotel-edge",
-	"autotel-cloudflare",
-	"autotel-nuxt",
-	"autotel-tanstack",
-	"autotel-hono",
-	"autotel-adapters"
-];
-/**
-* Files where a framework integration is wired up.
-*
-* Kept to a fixed list rather than a glob: this answers "did anyone install the
-* middleware", and the answer is always in the app's entry file or its hooks.
-*/
-const WIRING_FILES = [
-	"src/index.ts",
-	"src/app.ts",
-	"src/server.ts",
-	"src/main.ts",
-	"index.ts",
-	"app.ts",
-	"server.ts",
-	"middleware.ts",
-	"src/middleware.ts",
-	"src/hooks.server.ts",
-	"hooks.server.ts",
-	"nuxt.config.ts",
-	"src/router.tsx",
-	"app/router.tsx"
-];
-/** Autotel framework integrations that create a request span when called. */
-const AMBIENT_APIS = ["autotelMiddleware", "autotelHandle"];
-function hasAmbientTracing(projectRoot, instrumentationPath) {
-	const parse = createParser();
-	const candidates = new Set([instrumentationPath, ...WIRING_FILES.map((file) => path$1.join(projectRoot, file))].filter((file) => file !== null && fileExists(file)));
-	for (const file of candidates) {
-		const source = parse(file);
-		if (source && usesAutotelApi$1(buildFileFacts(source), AMBIENT_APIS)) return true;
-	}
-	return false;
-}
-function projectSource(projectRoot) {
-	const files = globSync("{src,app,server,routes,pages}/**/*.{ts,tsx,js,jsx,mts,mjs}", {
-		cwd: projectRoot,
-		absolute: true,
-		ignore: [
-			"**/node_modules/**",
-			"**/dist/**",
-			"**/*.test.*",
-			"**/*.spec.*"
-		]
-	});
-	const occurrences = /* @__PURE__ */ new Map();
-	const chunks = [];
-	const call = /createStructuredError\s*\(\s*\{([\s\S]*?)\}\s*\)/g;
-	for (const file of files) {
-		const source = readFileSafe(file) ?? "";
-		chunks.push(source);
-		for (const match of source.matchAll(call)) {
-			const body = match[1] ?? "";
-			const message = /\bmessage\s*:\s*(['"`])([\s\S]*?)\1/.exec(body)?.[2];
-			const status = /\bstatus\s*:\s*(\d+)/.exec(body)?.[1];
-			if (!message || !status) continue;
-			const signature = `${status}|${message}`;
-			const entry = occurrences.get(signature) ?? {
-				label: message,
-				files: /* @__PURE__ */ new Set()
-			};
-			entry.files.add(path$1.relative(projectRoot, file).split(path$1.sep).join("/"));
-			occurrences.set(signature, entry);
-		}
-	}
-	return {
-		text: chunks.join("\n"),
-		repeatedErrors: new Map([...occurrences].filter(([, entry]) => entry.files.size > 1).map(([signature, entry]) => [signature, {
-			label: entry.label,
-			files: [...entry.files].toSorted()
-		}]))
-	};
-}
-function collectDeps(pkg) {
-	return /* @__PURE__ */ new Set([...Object.keys(pkg?.dependencies ?? {}), ...Object.keys(pkg?.devDependencies ?? {})]);
-}
-function collectProjectFacts(projectRoot) {
-	const pkg = readJsonSafe(path$1.join(projectRoot, "package.json"));
-	const deps = collectDeps(pkg);
-	const instrumentation = findInstrumentationFile(projectRoot);
-	const instrumentationText = instrumentation ? readFileSafe(instrumentation.path) ?? "" : "";
-	const ambientText = `${instrumentationText}\n${WIRING_FILES.map((candidate) => fileExists(path$1.join(projectRoot, candidate)) ? readFileSafe(path$1.join(projectRoot, candidate)) ?? "" : "").join("\n")}`;
-	const source = projectSource(projectRoot);
-	const projectSignalText = `${ambientText}\n${source.text}`;
-	return {
-		name: pkg?.name ?? path$1.basename(projectRoot),
-		deps,
-		hasAutotel: RUNTIME_AUTOTEL_PACKAGES.some((name) => deps.has(name)),
-		ambientTracing: deps.has("autotel-nuxt") || hasAmbientTracing(projectRoot, instrumentation?.path ?? null),
-		hasRedaction: instrumentationText.includes("attributeRedactor"),
-		instrumentationFile: instrumentation ? path$1.relative(projectRoot, instrumentation.path).split(path$1.sep).join("/") : null,
-		hasLlmDependency: LLM_PACKAGES.some((name) => deps.has(name)),
-		hasZod: deps.has("zod"),
-		hasAuditUsage: deps.has("autotel-audit") && /securityEvent|withSecurity|withAudit|defineAuditCatalog/.test(projectSignalText),
-		hasErrorCatalog: projectSignalText.includes("defineErrorCatalog"),
-		repeatedErrors: source.repeatedErrors
-	};
-}
-//#endregion
 //#region src/lib/map/sensitivity.ts
 const MONEY_PACKAGES = [
 	"stripe",
@@ -5932,6 +5797,10 @@ function lostPoints(route) {
 	const weight = route.sensitivity.level === "high" ? 2 : 1;
 	return (100 - route.score) * weight;
 }
+/** Entry points with gaps, most points lost first: the "Fix these first" order. */
+function fixFirst(routes) {
+	return routes.filter((route) => classifyRouteObservability(route) !== "exempt" && route.score < 100).toSorted((a, b) => lostPoints(b) - lostPoints(a));
+}
 /**
 * The default view: the number, the tally, and the three entry points worth
 * fixing first.
@@ -5948,7 +5817,7 @@ function formatReport(result, options = {}) {
 	lines.push("");
 	lines.push(`  ${colour(chalk.bold(`${map.score}/100`))}  ${colour(grade)}`);
 	lines.push(chalk.dim(`  ${map.routes.length} entry point${map.routes.length === 1 ? "" : "s"} · ${summary.instrumented} instrumented · ${summary.partial} partial · ${summary.dark} dark · ${summary.exempt} exempt` + (summary.suppressedChecks > 0 ? ` · ${summary.suppressedChecks} suppressed` : "")));
-	const worst = map.routes.filter((route) => classifyRouteObservability(route) !== "exempt" && route.score < 100).toSorted((a, b) => lostPoints(b) - lostPoints(a)).slice(0, 3);
+	const worst = fixFirst(map.routes).slice(0, 3);
 	if (worst.length > 0) {
 		lines.push("");
 		lines.push(chalk.bold("Fix these first"));
@@ -6057,6 +5926,207 @@ function formatGate(score, threshold) {
 	return score < threshold ? chalk.red(`\nScore ${score} is below --min-score ${threshold}.`) : chalk.green(`\nScore ${score} meets --min-score ${threshold}.`);
 }
 //#endregion
+//#region src/lib/map/github.ts
+function rebase(file, location) {
+	if (!location.workspace) return file;
+	return path$1.relative(location.workspace, path$1.resolve(location.projectRoot, file)).split(path$1.sep).join("/");
+}
+/** The failing requirements of one entry point, at the evidence line when a check has one. */
+function failures(route) {
+	const out = [];
+	for (const [check, result] of Object.entries(route.checks)) {
+		if (result.status !== "fail") continue;
+		out.push({
+			file: result.evidence?.file ?? route.file,
+			line: result.evidence?.line ?? route.handler?.line ?? 1,
+			check,
+			message: result.message ?? getRule(check)?.question ?? check
+		});
+	}
+	return out;
+}
+/**
+* Checks that passed in the baseline and no longer do. These are the pull
+* request's; everything else on the map predates it and is already in the score.
+*/
+function regressions(scan, baseline) {
+	const routes = new Map(scan.map.routes.map((route) => [route.id, route]));
+	return baseline.regressions.flatMap((regression) => {
+		const route = routes.get(regression.routeId);
+		if (!route) return [];
+		const failed = failures(route).find((finding) => finding.check === regression.check);
+		if (failed) return [failed];
+		return [{
+			file: route.file,
+			line: route.handler?.line ?? 1,
+			check: regression.check,
+			message: `${regression.check} passed in ${baseline.source.label} and is now suppressed`
+		}];
+	});
+}
+function escapeMessage(text) {
+	return text.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+}
+function escapeProperty(text) {
+	return escapeMessage(text).replaceAll(":", "%3A").replaceAll(",", "%2C");
+}
+function annotation(level, properties, message) {
+	const props = Object.entries(properties).map(([key, value]) => `${key}=${escapeProperty(value)}`).join(",");
+	return `::${level}${props ? ` ${props}` : ""}::${escapeMessage(message)}`;
+}
+/**
+* GitHub Actions workflow commands, one line per finding, for stdout.
+*
+* With a baseline, the findings are the regressions and they are errors: the
+* pull request caused them. Without one, they are the "Fix these first" list,
+* worst entry point first, as warnings. Either list stops at `limit`. The
+* first line carries the score, as an error when the gate failed, so the run
+* is readable without the log. It leads because GitHub keeps only the first
+* ten errors of a step.
+*/
+function formatGithubAnnotations(scan, baseline, location, options) {
+	const findings = baseline ? regressions(scan, baseline) : fixFirst(scan.map.routes).flatMap(failures);
+	const level = baseline ? "error" : "warning";
+	const lines = findings.slice(0, options.limit).map((finding) => annotation(level, {
+		file: rebase(finding.file, location),
+		line: String(finding.line),
+		title: `autotel map: ${finding.check}`
+	}, finding.message));
+	const { score } = scan.map;
+	const { dark, instrumented, partial } = scan.summary;
+	const hidden = findings.length - lines.length;
+	const summary = `score ${score}/100 (${scan.grade}): ${instrumented} instrumented, ${partial} partial, ${dark} dark` + (hidden > 0 ? `; ${hidden} more finding${hidden === 1 ? "" : "s"} not shown` : "");
+	const title = { title: "autotel map" };
+	let headline;
+	if (options.minScore !== void 0 && score < options.minScore) headline = annotation("error", title, `${summary}; below --min-score ${options.minScore}`);
+	else if (baseline && hasRegressed(baseline)) headline = annotation("error", title, `${summary}; regressed against ${baseline.source.label}`);
+	else headline = annotation("notice", title, summary);
+	return [headline, ...lines].join("\n");
+}
+//#endregion
+//#region src/lib/map/project-facts.ts
+const LLM_PACKAGES = [
+	"openai",
+	"@anthropic-ai/sdk",
+	"ai",
+	"@ai-sdk/openai",
+	"@ai-sdk/anthropic",
+	"@ai-sdk/google",
+	"ai-sdk-ollama",
+	"ollama",
+	"@google/generative-ai",
+	"@mistralai/mistralai",
+	"cohere-ai",
+	"langchain",
+	"@langchain/core"
+];
+const RUNTIME_AUTOTEL_PACKAGES = [
+	"autotel",
+	"autotel-edge",
+	"autotel-cloudflare",
+	"autotel-nuxt",
+	"autotel-tanstack",
+	"autotel-hono",
+	"autotel-adapters"
+];
+/**
+* Files where a framework integration is wired up.
+*
+* Kept to a fixed list rather than a glob: this answers "did anyone install the
+* middleware", and the answer is always in the app's entry file or its hooks.
+*/
+const WIRING_FILES = [
+	"src/index.ts",
+	"src/app.ts",
+	"src/server.ts",
+	"src/main.ts",
+	"index.ts",
+	"app.ts",
+	"server.ts",
+	"middleware.ts",
+	"src/middleware.ts",
+	"src/hooks.server.ts",
+	"hooks.server.ts",
+	"nuxt.config.ts",
+	"src/router.tsx",
+	"app/router.tsx"
+];
+/** Autotel framework integrations that create a request span when called. */
+const AMBIENT_APIS = ["autotelMiddleware", "autotelHandle"];
+function hasAmbientTracing(projectRoot, instrumentationPath) {
+	const parse = createParser();
+	const candidates = new Set([instrumentationPath, ...WIRING_FILES.map((file) => path$1.join(projectRoot, file))].filter((file) => file !== null && fileExists(file)));
+	for (const file of candidates) {
+		const source = parse(file);
+		if (source && usesAutotelApi$1(buildFileFacts(source), AMBIENT_APIS)) return true;
+	}
+	return false;
+}
+function projectSource(projectRoot) {
+	const files = globSync("{src,app,server,routes,pages}/**/*.{ts,tsx,js,jsx,mts,mjs}", {
+		cwd: projectRoot,
+		absolute: true,
+		ignore: [
+			"**/node_modules/**",
+			"**/dist/**",
+			"**/*.test.*",
+			"**/*.spec.*"
+		]
+	});
+	const occurrences = /* @__PURE__ */ new Map();
+	const chunks = [];
+	const call = /createStructuredError\s*\(\s*\{([\s\S]*?)\}\s*\)/g;
+	for (const file of files) {
+		const source = readFileSafe(file) ?? "";
+		chunks.push(source);
+		for (const match of source.matchAll(call)) {
+			const body = match[1] ?? "";
+			const message = /\bmessage\s*:\s*(['"`])([\s\S]*?)\1/.exec(body)?.[2];
+			const status = /\bstatus\s*:\s*(\d+)/.exec(body)?.[1];
+			if (!message || !status) continue;
+			const signature = `${status}|${message}`;
+			const entry = occurrences.get(signature) ?? {
+				label: message,
+				files: /* @__PURE__ */ new Set()
+			};
+			entry.files.add(path$1.relative(projectRoot, file).split(path$1.sep).join("/"));
+			occurrences.set(signature, entry);
+		}
+	}
+	return {
+		text: chunks.join("\n"),
+		repeatedErrors: new Map([...occurrences].filter(([, entry]) => entry.files.size > 1).map(([signature, entry]) => [signature, {
+			label: entry.label,
+			files: [...entry.files].toSorted()
+		}]))
+	};
+}
+function collectDeps(pkg) {
+	return /* @__PURE__ */ new Set([...Object.keys(pkg?.dependencies ?? {}), ...Object.keys(pkg?.devDependencies ?? {})]);
+}
+function collectProjectFacts(projectRoot) {
+	const pkg = readJsonSafe(path$1.join(projectRoot, "package.json"));
+	const deps = collectDeps(pkg);
+	const instrumentation = findInstrumentationFile(projectRoot);
+	const instrumentationText = instrumentation ? readFileSafe(instrumentation.path) ?? "" : "";
+	const ambientText = `${instrumentationText}\n${WIRING_FILES.map((candidate) => fileExists(path$1.join(projectRoot, candidate)) ? readFileSafe(path$1.join(projectRoot, candidate)) ?? "" : "").join("\n")}`;
+	const source = projectSource(projectRoot);
+	const projectSignalText = `${ambientText}\n${source.text}`;
+	return {
+		name: pkg?.name ?? path$1.basename(projectRoot),
+		deps,
+		hasAutotel: RUNTIME_AUTOTEL_PACKAGES.some((name) => deps.has(name)),
+		ambientTracing: deps.has("autotel-nuxt") || hasAmbientTracing(projectRoot, instrumentation?.path ?? null),
+		hasRedaction: instrumentationText.includes("attributeRedactor"),
+		instrumentationFile: instrumentation ? path$1.relative(projectRoot, instrumentation.path).split(path$1.sep).join("/") : null,
+		hasLlmDependency: LLM_PACKAGES.some((name) => deps.has(name)),
+		hasZod: deps.has("zod"),
+		hasAuditUsage: deps.has("autotel-audit") && /securityEvent|withSecurity|withAudit|defineAuditCatalog/.test(projectSignalText),
+		hasErrorCatalog: projectSignalText.includes("defineErrorCatalog"),
+		repeatedErrors: source.repeatedErrors
+	};
+}
+//#endregion
 //#region src/lib/map/scan.ts
 /** Stable identity for an entry point, so a baseline can match it across runs. */
 function routeId(route) {
@@ -6182,6 +6252,46 @@ function parseMinScore(value) {
 	});
 	return threshold;
 }
+const FORMATS = [
+	"human",
+	"json",
+	"github"
+];
+/**
+* Read `--format`, with `--json` as the long-standing spelling of `--format
+* json`. Two formats cannot share stdout, so asking for both is refused rather
+* than letting one silently win.
+*/
+function parseFormat(value, json) {
+	if (value === void 0 || value === "") return json ? "json" : "human";
+	const format = FORMATS.find((name) => name === value);
+	if (!format) throw new AutotelError({
+		type: "validation",
+		code: AutotelErrorCodes.E_INVALID_FLAG,
+		message: `Unknown --format "${value}"`,
+		fix: `Pass one of: ${FORMATS.join(", ")}`,
+		expected: { formats: [...FORMATS] }
+	});
+	if (json && format !== "json") throw new AutotelError({
+		type: "validation",
+		code: AutotelErrorCodes.E_INVALID_FLAG,
+		message: `--json and --format ${format} both claim stdout`,
+		fix: "Drop --json, or pass --format json"
+	});
+	return format;
+}
+/** Read `--limit`; the whole string has to parse, for the same reason as `--min-score`. */
+function parseLimit(value) {
+	if (value === void 0 || value === "") return 10;
+	const limit = Number(value);
+	if (!Number.isInteger(limit) || limit < 1) throw new AutotelError({
+		type: "validation",
+		code: AutotelErrorCodes.E_INVALID_FLAG,
+		message: `--limit expects a whole number of 1 or more, got "${value}"`,
+		fix: "Pass e.g. --limit 10"
+	});
+	return limit;
+}
 function resolveFramework(requested, projectRoot, deps) {
 	if (requested !== void 0 && requested !== "") {
 		if (!isFramework(requested)) throw new AutotelError({
@@ -6268,9 +6378,25 @@ function runMap(options) {
 		...options.outputFile !== void 0 ? { outputFile: options.outputFile } : {},
 		outputRoot: options.cwd
 	});
+	const format = parseFormat(options.format, options.json);
+	const limit = parseLimit(options.limit);
 	const minScore = parseMinScore(options.minScore);
 	const result = runMapScan(options);
-	if (options.json) printJson({
+	const human = () => formatMapResult(result, {
+		all: options.all,
+		...options.entry !== void 0 ? { entry: options.entry } : {},
+		...minScore !== void 0 ? { minScore } : {}
+	});
+	if (format === "github") {
+		process.stdout.write(`${formatGithubAnnotations(result.scan, result.baseline, {
+			projectRoot: result.projectRoot,
+			...process.env.GITHUB_WORKSPACE ? { workspace: process.env.GITHUB_WORKSPACE } : {}
+		}, {
+			limit,
+			...minScore !== void 0 ? { minScore } : {}
+		})}\n`);
+		process.stderr.write(`${human()}\n`);
+	} else if (format === "json") printJson({
 		ok: true,
 		command: "map",
 		mapFile: MAP_FILE_NAME,
@@ -6283,11 +6409,7 @@ function runMap(options) {
 		...result.baseline ? { baseline: result.baseline } : {},
 		map: result.scan.map
 	});
-	else process.stdout.write(`${formatMapResult(result, {
-		all: options.all,
-		...options.entry !== void 0 ? { entry: options.entry } : {},
-		...minScore !== void 0 ? { minScore } : {}
-	})}\n`);
+	else process.stdout.write(`${human()}\n`);
 	if (minScore !== void 0 && result.scan.map.score < minScore) {
 		process.exitCode = 1;
 		return;
@@ -9631,7 +9753,7 @@ function createProgram() {
 	});
 	addGlobalOptions(addCmd);
 	program.addCommand(addCmd);
-	const mapCmd = new Command("map").description("Score the observability of every entry point in your project").argument("[entry]", "Inspect one entry point by route or file path").option("--framework <name>", "Override framework detection (next, nitro, tanstack-start, sveltekit, hono, express, fastify, elysia, cloudflare)").option("--all", "Show every entry point as a check matrix").option("--min-score <n>", "Exit 1 when the global score is below this threshold").option("--baseline [source]", "Compare against a committed autotel.map.json and exit 1 on regression (path, or git:<ref>)").option("--no-write", "Skip writing autotel.map.json").option("--json", "Output machine-readable JSON").option("--output-file <path>", "Persist JSON output to this path").option("--workspace-root", "Scan from the workspace root instead of the package root").action((entry, opts) => {
+	const mapCmd = new Command("map").description("Score the observability of every entry point in your project").argument("[entry]", "Inspect one entry point by route or file path").option("--framework <name>", "Override framework detection (next, nitro, tanstack-start, sveltekit, hono, express, fastify, elysia, cloudflare)").option("--all", "Show every entry point as a check matrix").option("--min-score <n>", "Exit 1 when the global score is below this threshold").option("--baseline [source]", "Compare against a committed autotel.map.json and exit 1 on regression (path, or git:<ref>)").option("--no-write", "Skip writing autotel.map.json").option("--json", "Output machine-readable JSON (same as --format json)").option("--format <name>", "Output: human (default), json, github (workflow annotations on stdout)").option("--limit <n>", "Most annotations --format github emits (default 10, GitHub's per-step cap)").option("--output-file <path>", "Persist JSON output to this path").option("--workspace-root", "Scan from the workspace root instead of the package root").action((entry, opts) => {
 		runMap({
 			cwd: opts.cwd ?? process.cwd(),
 			dryRun: false,
@@ -9647,6 +9769,8 @@ function createProgram() {
 			baseline: opts.baseline,
 			write: opts.write !== false,
 			json: opts.json ?? false,
+			format: opts.format,
+			limit: opts.limit,
 			outputFile: opts.outputFile
 		});
 	});
@@ -9772,7 +9896,7 @@ async function run() {
 	});
 	program.exitOverride();
 	const argvJoined = process.argv.slice(2).join(" ");
-	const isJsonOnly = process.argv.includes("--json") || /^(schema|commands|examples|version|health|capabilities|discover|query|trace|diagnose|topology|correlate|llm|semconv|score|collector)\b/.test(argvJoined);
+	const isJsonOnly = process.argv.includes("--json") || /(^|\s)--format(=|\s+)json\b/.test(argvJoined) || /^(schema|commands|examples|version|health|capabilities|discover|query|trace|diagnose|topology|correlate|llm|semconv|score|collector)\b/.test(argvJoined);
 	if (isJsonOnly) program.configureOutput({ writeErr: () => {} });
 	const stack = [...program.commands];
 	while (stack.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-cli",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "CLI for autotel - setup wizard, diagnostics, and incremental features",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
   "dependencies": {
     "@inquirer/prompts": "^8.7.2",
     "@opentelemetry/otlp-transformer": "^0.222.0",
-    "autotel-mcp": "0.12.0",
+    "autotel-mcp": "0.13.0",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "glob": "^13.0.6",