@andesyte-oss/cli 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 Foundation Machines Ltd.
3
+ Copyright (c) 2026 Andesyte
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,57 +1,141 @@
1
- # @andesyte-oss/cli
1
+ # Andesyte CLI
2
2
 
3
- Local security checks for code and dependencies — CLI and MCP server.
3
+ Local AI-code checks and dependency preflight for humans, CI and coding agents.
4
+ This repository contains an unreleased reliability candidate. Its behaviour may
5
+ not match the current npm release. Publication requires separate verification.
4
6
 
5
- Source code never leaves your machine.
7
+ ## What it checks
8
+
9
+ Code checks use packaged Semgrep rules for model output reaching execution,
10
+ shell commands or unsafe HTML; credential-shaped prompt literals. There are six active rules: four apply to Python and two each
11
+ to JavaScript and TypeScript. This is not general SAST, prompt-injection
12
+ prevention, authorization review or a general secret scanner.
13
+
14
+ Dependency checks query exact coordinates from qualified npm, pnpm and narrow
15
+ Python requirements inputs. Unqualified formats and unresolved records remain
16
+ visible as coverage gaps. See [Capabilities](../../docs/CAPABILITIES.md).
6
17
 
7
18
  ## Install
8
19
 
9
- ```bash
20
+ Requires Node.js >=20.19. Semgrep is a separate prerequisite for code checks.
21
+ Nothing installs an engine or downloads rules at runtime.
22
+
23
+ ```sh
10
24
  npm install -g @andesyte-oss/cli
25
+ uv tool install semgrep
11
26
  ```
12
27
 
13
- Requires Node.js >= 20.19. `check_code` additionally requires
14
- [Semgrep](https://semgrep.dev) on your PATH:
15
-
16
- ```bash
17
- uv tool install semgrep # or: pipx install semgrep
18
- ```
28
+ Pin a reviewed released CLI version in CI. Qualification currently uses Semgrep
29
+ 1.176.0. A newer engine needs compatibility testing before it is recommended.
19
30
 
20
- ## CLI
31
+ ## Run
21
32
 
22
- ```bash
33
+ ```sh
23
34
  andesyte check code --changed
24
35
  andesyte check dependencies --changed
25
36
  andesyte check code --staged
26
- andesyte check code --all
27
- andesyte check code --path src/auth.ts
28
- andesyte check dependencies --json
37
+ andesyte check dependencies --staged
38
+ andesyte check code --path src/agent.py --json
39
+ andesyte check dependencies --path package-lock.json --json
40
+ andesyte check code --changed --base origin/main
41
+ ```
42
+
43
+ - `changed` selects uncommitted files, or differences from an explicit base.
44
+ - `staged` checks Git index bytes, including staged suppression policy. Unstaged
45
+ replacements cannot hide vulnerable content that will be committed.
46
+ - Code checks scan entire selected files, not only newly introduced findings.
47
+ - Dependency `changed`/`staged` checks compare coordinates with the base. An
48
+ explicit dependency path checks all its coordinates unless `--base` is given.
49
+ - `--all` discovers the whole repository, subject to caps. Recognized manifests
50
+ without qualified resolution make dependency coverage partial. A lockfile's
51
+ mere presence does not prove every manifest change was resolved.
52
+ - No selected targets is not evidence that the repository was checked.
53
+
54
+ | Exit | Meaning |
55
+ |---|---|
56
+ | 0 | Complete selected scope, no unsuppressed findings |
57
+ | 1 | Complete selected scope with findings |
58
+ | 2 | Invalid invocation |
59
+ | 3 | Failed or incomplete check, possibly with findings |
60
+
61
+ Do not narrow away coverage gaps to obtain exit 0. Read findings in context and
62
+ verify any changes with the application's tests.
63
+
64
+ ## MCP
65
+
66
+ The stdio server exposes only `check_code` and `check_dependencies`. Both use the
67
+ same project policy as the CLI. Its root is fixed at startup; configure it
68
+ explicitly rather than assuming the client's working directory.
69
+
70
+ ### Claude Code
71
+
72
+ ```sh
73
+ claude mcp add andesyte -- npx -y @andesyte-oss/cli mcp --cwd /absolute/project
29
74
  ```
30
75
 
31
- Exit codes: `0` complete and clean · `1` findings · `2` usage error ·
32
- `3` result not trustworthy (engine missing, scan failed, or coverage incomplete).
76
+ ### Codex
33
77
 
34
- ## MCP server
78
+ In the client's `config.toml`:
35
79
 
36
- ```bash
37
- andesyte mcp
80
+ ```toml
81
+ [mcp_servers.andesyte]
82
+ command = "npx"
83
+ args = ["-y", "@andesyte-oss/cli", "mcp", "--cwd", "/absolute/project"]
38
84
  ```
39
85
 
40
- Exposes two stdio tools: `check_code` and `check_dependencies`.
86
+ ### Zed
41
87
 
42
88
  ```json
43
- {
44
- "mcpServers": {
45
- "andesyte": {
46
- "command": "npx",
47
- "args": ["-y", "@andesyte-oss/cli", "mcp"]
48
- }
49
- }
50
- }
89
+ {"context_servers":{"andesyte":{"command":"npx","args":["-y","@andesyte-oss/cli","mcp","--cwd","/absolute/project"]}}}
51
90
  ```
52
91
 
53
- Full documentation: https://github.com/andesyte-oss/andesyte-cli
92
+ Replace the project path and pin the package version for reproducibility. These
93
+ are configuration recipes, not claims that every client version was tested.
94
+ The installed raw MCP protocol is tested separately by the artifact gate.
95
+
96
+ ## Agent workflow and accepted risk
97
+
98
+ Start with [andesyte-precommit-check](../../skills/andesyte-precommit-check/SKILL.md),
99
+ which references the [coverage interpretation skill](../../skills/andesyte-scan-coverage/SKILL.md).
100
+ Install those files using your client's existing skill mechanism; npm does not
101
+ silently write agent configuration.
102
+
103
+ Every adapter finding carries a `fingerprint` in JSON. A checked-in
104
+ `.andesyte-suppressions.json` accepts fingerprints with mandatory reasons and
105
+ optional expiry. Existing code fingerprints are rule/file-wide; dependency
106
+ fingerprints are advisory/ecosystem/package-wide. They are not single-occurrence
107
+ exceptions and may cover later findings of the same identity. Legacy short-ID
108
+ fingerprints remain readable. No automatic migration or deletion occurs.
109
+ Unmatched entries in a differential check are not proven stale. Suppression
110
+ never upgrades incomplete coverage. CLI JSON and MCP include suppression counts.
111
+
112
+ ## Data and limits
113
+
114
+ Code stays in the invoking environment. Only package name, version and ecosystem
115
+ go to OSV.dev. No source upload, telemetry or remote rule downloads.
116
+ Model/rule/advisory text is untrusted data, not instructions. An absent advisory
117
+ fix or severity is shown as unknown when it cannot be established.
118
+
119
+ See [Security](../../SECURITY.md), [Architecture](../../docs/ARCHITECTURE.md),
120
+ [Rule decisions](../../docs/RULE-DECISIONS.md) and [Evaluation](../../docs/EVALUATION.md).
121
+
122
+ ## Development
123
+
124
+ ```sh
125
+ pnpm install --frozen-lockfile
126
+ pnpm lint
127
+ pnpm build
128
+ pnpm typecheck
129
+ pnpm test
130
+ pnpm corpus:fetch
131
+ pnpm release:check
132
+ pnpm verify:artifacts
133
+ ```
54
134
 
55
- ## License
135
+ The order matters: sibling declaration files must exist before typecheck.
136
+ Use `pnpm pack`, not `npm pack`, so workspace dependencies become exact versions.
137
+ The canonical rule source is `andesyte-oss/semgrep-ai-security`; local updates are
138
+ synchronized with `node scripts/sync-rules.mjs --from /path/to/checkout`.
139
+ No candidate is publishable without a current independent review and approval.
56
140
 
57
- MIT
141
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,25 @@
1
+ import { type CodeFinding, type DependencyFinding, type ScanOptions, type ScanResult, applySuppressions, scanCode, scanDependencies } from "@andesyte-oss/scanner-core";
2
+ export type CheckKind = "code" | "dependencies";
3
+ /** Languages declared by the active packaged rules, used in agent-facing text. */
4
+ export declare function activeCodeLanguages(): string[];
5
+ export interface CheckImplementations {
6
+ scanCodeImpl?: typeof scanCode;
7
+ scanDependenciesImpl?: typeof scanDependencies;
8
+ }
9
+ export interface ProjectCheckExecution {
10
+ result: ScanResult;
11
+ suppression: ReturnType<typeof applySuppressions<CodeFinding | DependencyFinding>>;
12
+ }
13
+ type ProjectSuppression = ProjectCheckExecution["suppression"];
14
+ /** Compact, bounded suppression context for terminals and coding agents. */
15
+ export declare function suppressionSummary(suppression: ProjectSuppression): string;
16
+ /** Detailed, quarantined suppression report for stderr. */
17
+ export declare function suppressionCliReport(suppression: ProjectSuppression): string;
18
+ /**
19
+ * Shared application layer for the CLI and MCP adapters.
20
+ *
21
+ * Ruleset composition and repository suppressions belong here so both adapters
22
+ * execute the same policy. Adapters only parse or format input and output.
23
+ */
24
+ export declare function runProjectCheck(kind: CheckKind, options: ScanOptions, implementations?: CheckImplementations, reviewSinks?: boolean): Promise<ProjectCheckExecution>;
25
+ export {};
package/dist/checks.js ADDED
@@ -0,0 +1,129 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { SUPPRESSIONS_FILE, applySuppressions, declaredRuleLanguages, fingerprintOf, loadSuppressions, quarantineText, scanCode, scanDependencies, } from "@andesyte-oss/scanner-core";
3
+ import { ruleset } from "@andesyte-oss/security-rules";
4
+ /** Languages declared by the active packaged rules, used in agent-facing text. */
5
+ export function activeCodeLanguages() {
6
+ const languages = new Set();
7
+ for (const rulePath of ruleset().rulePaths) {
8
+ try {
9
+ for (const language of declaredRuleLanguages(readFileSync(rulePath, "utf8"))) {
10
+ languages.add(language);
11
+ }
12
+ }
13
+ catch {
14
+ // scanCode reports missing or invalid rules as an engine failure.
15
+ }
16
+ }
17
+ return [...languages].sort();
18
+ }
19
+ /** Compact, bounded suppression context for terminals and coding agents. */
20
+ export function suppressionSummary(suppression) {
21
+ const lines = [];
22
+ if (suppression.suppressed.length > 0) {
23
+ const details = suppression.suppressed
24
+ .slice(0, 10)
25
+ .map((item) => `${item.finding.id} (${quarantineText(item.reason)})`)
26
+ .join(", ");
27
+ lines.push(`${suppression.suppressed.length} finding${suppression.suppressed.length === 1 ? "" : "s"} suppressed: ${details}`);
28
+ }
29
+ if (suppression.expiredFingerprints.length > 0) {
30
+ lines.push(`${suppression.expiredFingerprints.length} suppression(s) expired and were not applied.`);
31
+ }
32
+ if (suppression.unusedFingerprints.length > 0) {
33
+ lines.push(`${suppression.unusedFingerprints.length} suppression(s) matched nothing.`);
34
+ }
35
+ return lines.join("\n");
36
+ }
37
+ /** Detailed, quarantined suppression report for stderr. */
38
+ export function suppressionCliReport(suppression) {
39
+ const lines = [];
40
+ if (suppression.suppressed.length > 0) {
41
+ lines.push(`\n${suppression.suppressed.length} finding(s) suppressed by ${SUPPRESSIONS_FILE}:`);
42
+ for (const item of suppression.suppressed) {
43
+ lines.push(` ${item.fingerprint} ${item.finding.id} — ${quarantineText(item.reason)}`);
44
+ }
45
+ }
46
+ if (suppression.expiredFingerprints.length > 0) {
47
+ lines.push(`\n${suppression.expiredFingerprints.length} suppression(s) have EXPIRED and were not applied: ${suppression.expiredFingerprints.join(", ")}`);
48
+ }
49
+ if (suppression.unusedFingerprints.length > 0) {
50
+ lines.push(`\n${suppression.unusedFingerprints.length} suppression(s) did not match this scope; this does not prove they are stale: ${suppression.unusedFingerprints.join(", ")}`);
51
+ }
52
+ return lines.length > 0 ? `${lines.join("\n")}\n` : "";
53
+ }
54
+ /**
55
+ * Shared application layer for the CLI and MCP adapters.
56
+ *
57
+ * Ruleset composition and repository suppressions belong here so both adapters
58
+ * execute the same policy. Adapters only parse or format input and output.
59
+ */
60
+ export async function runProjectCheck(kind, options, implementations = {}, reviewSinks = false) {
61
+ const loaded = await (options.scope === "staged"
62
+ ? loadSuppressions(options.root, "staged")
63
+ : loadSuppressions(options.root));
64
+ let raw;
65
+ if (kind === "code") {
66
+ const descriptor = ruleset({ reviewSinks });
67
+ raw = await (implementations.scanCodeImpl ?? scanCode)(options, {
68
+ rulePaths: descriptor.rulePaths,
69
+ rulesetName: descriptor.name,
70
+ rulesetVersion: descriptor.version,
71
+ languageExtensions: descriptor.languageExtensions,
72
+ });
73
+ }
74
+ else {
75
+ raw = await (implementations.scanDependenciesImpl ?? scanDependencies)(options);
76
+ }
77
+ raw = {
78
+ ...raw,
79
+ findings: raw.findings.map((finding) => {
80
+ const review = finding.kind === "code" && finding.rule_id?.startsWith("ai.sink-review.");
81
+ return {
82
+ ...finding,
83
+ ...(review ? { confidence: "low", analysis_kind: "sink-review" } : {}),
84
+ fingerprint: fingerprintOf(finding),
85
+ };
86
+ }),
87
+ };
88
+ try {
89
+ await loaded.verifySnapshot?.();
90
+ }
91
+ catch {
92
+ loaded.entries = [];
93
+ loaded.errors.push("index changed during check; suppressions were not applied");
94
+ raw = { ...raw, status: "failed" };
95
+ }
96
+ const suppression = applySuppressions(raw.findings, loaded.entries);
97
+ const result = {
98
+ ...raw,
99
+ scope: {
100
+ ...raw.scope,
101
+ selection: options.scope,
102
+ content: options.scope === "staged" ? "git-index" : "working-tree",
103
+ requested_base: options.baseRef ?? null,
104
+ ...(raw.coverage.requested === 0
105
+ ? {
106
+ empty_reason: "No targets selected. This is not evidence that the repository was checked.",
107
+ }
108
+ : {}),
109
+ },
110
+ suppression: {
111
+ suppressed: suppression.suppressed.length,
112
+ expired: suppression.expiredFingerprints.length,
113
+ unused: suppression.unusedFingerprints.length,
114
+ },
115
+ status: raw.status === "complete" && loaded.errors.length > 0 ? "partial" : raw.status,
116
+ findings: suppression.kept,
117
+ errors: [
118
+ ...raw.errors,
119
+ ...loaded.errors.map((message) => ({ code: "parse_failed", message })),
120
+ ].map((error) => ({
121
+ ...error,
122
+ message: quarantineText(error.message),
123
+ ...("remediation" in error && error.remediation
124
+ ? { remediation: quarantineText(error.remediation) }
125
+ : {}),
126
+ })),
127
+ };
128
+ return { result, suppression };
129
+ }
@@ -0,0 +1,40 @@
1
+ import { semgrepVersion } from "@andesyte-oss/scanner-core";
2
+ export type DoctorStatus = "ready" | "unavailable" | "attention";
3
+ export interface DoctorCapability {
4
+ status: DoctorStatus;
5
+ detail: string;
6
+ /** Stable documentation URL for this capability, shown when unavailable. */
7
+ docs?: string;
8
+ }
9
+ export interface DoctorReport {
10
+ version: "doctor/v1";
11
+ updates_checked: boolean;
12
+ capabilities: Record<"runtime" | "rules" | "code_scan" | "dependency_scan" | "git_pr_scan" | "github_pr_scan", DoctorCapability>;
13
+ updates: {
14
+ cli: {
15
+ installed: string;
16
+ latest: string | null;
17
+ status: "current" | "available" | "unavailable";
18
+ };
19
+ };
20
+ }
21
+ export interface DoctorDeps {
22
+ nodeVersion?: string;
23
+ semgrepVersion?: typeof semgrepVersion;
24
+ rules?: () => {
25
+ name: string;
26
+ version: string;
27
+ rulePaths: string[];
28
+ };
29
+ command?: (command: string, args: string[]) => Promise<string | null>;
30
+ latestVersion?: (packageName: string) => Promise<string | null>;
31
+ }
32
+ /**
33
+ * Reports prerequisites for the CLI's independently usable capabilities. The
34
+ * default path performs local probes only. Update checking is explicit because
35
+ * it contacts the npm registry, and never installs or changes anything.
36
+ */
37
+ export declare function collectDoctor(root: string, options?: {
38
+ checkUpdates?: boolean;
39
+ }, deps?: DoctorDeps): Promise<DoctorReport>;
40
+ export declare function formatDoctor(report: DoctorReport): string;
package/dist/doctor.js ADDED
@@ -0,0 +1,156 @@
1
+ import { execFile } from "node:child_process";
2
+ import { promisify } from "node:util";
3
+ import { semgrepVersion } from "@andesyte-oss/scanner-core";
4
+ import { ruleset } from "@andesyte-oss/security-rules";
5
+ import { VERSION } from "./version.js";
6
+ const execFileAsync = promisify(execFile);
7
+ const MINIMUM_NODE = [20, 19, 0];
8
+ /** One link per capability. A new capability key without a link fails typecheck. */
9
+ const CAPABILITY_DOCS = {
10
+ runtime: "https://docs.andesyte.com/cli/install",
11
+ rules: "https://docs.andesyte.com/cli/install",
12
+ code_scan: "https://docs.andesyte.com/cli/install#semgrep",
13
+ dependency_scan: "https://docs.andesyte.com/cli/coverage#osv",
14
+ git_pr_scan: "https://docs.andesyte.com/cli/scopes",
15
+ github_pr_scan: "https://docs.andesyte.com/cli/github-prs",
16
+ };
17
+ function parseVersion(value) {
18
+ const match = /^(\d+)\.(\d+)\.(\d+)/.exec(value);
19
+ if (!match)
20
+ return null;
21
+ const parsed = match.slice(1).map(Number);
22
+ return parsed.every(Number.isSafeInteger) ? parsed : null;
23
+ }
24
+ function versionAtLeast(actual, expected) {
25
+ const parsed = parseVersion(actual);
26
+ if (!parsed)
27
+ return false;
28
+ for (let index = 0; index < expected.length; index += 1) {
29
+ if (parsed[index] !== expected[index])
30
+ return (parsed[index] ?? 0) > (expected[index] ?? 0);
31
+ }
32
+ return true;
33
+ }
34
+ async function defaultCommand(command, args) {
35
+ try {
36
+ const { stdout } = await execFileAsync(command, args, {
37
+ timeout: 10_000,
38
+ maxBuffer: 1024 * 1024,
39
+ encoding: "utf8",
40
+ env: { ...process.env, SEMGREP_ENABLE_VERSION_CHECK: "0" },
41
+ });
42
+ return stdout.trim();
43
+ }
44
+ catch {
45
+ return null;
46
+ }
47
+ }
48
+ async function defaultLatestVersion(packageName) {
49
+ const output = await defaultCommand("npm", [
50
+ "view",
51
+ packageName,
52
+ "dist-tags.latest",
53
+ "--json",
54
+ "--registry=https://registry.npmjs.org",
55
+ ]);
56
+ if (!output)
57
+ return null;
58
+ try {
59
+ const version = JSON.parse(output);
60
+ return typeof version === "string" && parseVersion(version) ? version : null;
61
+ }
62
+ catch {
63
+ return null;
64
+ }
65
+ }
66
+ /**
67
+ * Reports prerequisites for the CLI's independently usable capabilities. The
68
+ * default path performs local probes only. Update checking is explicit because
69
+ * it contacts the npm registry, and never installs or changes anything.
70
+ */
71
+ export async function collectDoctor(root, options = {}, deps = {}) {
72
+ const command = deps.command ?? defaultCommand;
73
+ const installedNode = deps.nodeVersion ?? process.versions.node;
74
+ const nodeReady = versionAtLeast(installedNode, MINIMUM_NODE);
75
+ const [semgrep, git, gitRepository, ghAuthenticated] = await Promise.all([
76
+ (deps.semgrepVersion ?? semgrepVersion)(),
77
+ command("git", ["--version"]),
78
+ command("git", ["-C", root, "rev-parse", "--is-inside-work-tree"]),
79
+ command("gh", ["auth", "status"]),
80
+ ]);
81
+ let packagedRules = null;
82
+ try {
83
+ packagedRules = (deps.rules ?? ruleset)();
84
+ }
85
+ catch {
86
+ // A missing package payload must be reported before code scanning starts.
87
+ }
88
+ const updatesChecked = options.checkUpdates === true;
89
+ const latest = updatesChecked
90
+ ? await (deps.latestVersion ?? defaultLatestVersion)("@andesyte-oss/cli")
91
+ : null;
92
+ const updateStatus = !updatesChecked || latest === VERSION ? "current" : latest ? "available" : "unavailable";
93
+ const capabilities = {
94
+ runtime: nodeReady
95
+ ? { status: "ready", detail: `Node.js ${installedNode}` }
96
+ : {
97
+ status: "unavailable",
98
+ detail: `Node.js >=${MINIMUM_NODE.join(".")} required; found ${installedNode}`,
99
+ },
100
+ rules: packagedRules && packagedRules.rulePaths.length > 0
101
+ ? {
102
+ status: "ready",
103
+ detail: `${packagedRules.name} ${packagedRules.version}, ${packagedRules.rulePaths.length} rules file(s)`,
104
+ }
105
+ : { status: "unavailable", detail: "packaged security rules are unavailable" },
106
+ code_scan: nodeReady && semgrep && packagedRules && packagedRules.rulePaths.length > 0
107
+ ? { status: "ready", detail: `Semgrep ${semgrep}` }
108
+ : {
109
+ status: "unavailable",
110
+ detail: "requires a supported Node.js runtime, packaged rules, and Semgrep on PATH",
111
+ },
112
+ dependency_scan: nodeReady
113
+ ? {
114
+ status: "ready",
115
+ detail: "local dependency parsing ready; OSV is contacted only when a scan needs it",
116
+ }
117
+ : { status: "unavailable", detail: "requires a supported Node.js runtime" },
118
+ git_pr_scan: git && gitRepository === "true"
119
+ ? { status: "ready", detail: "Git repository available" }
120
+ : { status: "unavailable", detail: "requires Git and a repository working directory" },
121
+ github_pr_scan: git && gitRepository === "true" && ghAuthenticated !== null
122
+ ? { status: "ready", detail: "uses the local gh and Git authentication sessions" }
123
+ : {
124
+ status: "unavailable",
125
+ detail: "optional: requires Git repository access and gh auth login",
126
+ },
127
+ };
128
+ for (const [name, capability] of Object.entries(capabilities)) {
129
+ if (capability.status !== "ready")
130
+ capability.docs = CAPABILITY_DOCS[name];
131
+ }
132
+ return {
133
+ version: "doctor/v1",
134
+ updates_checked: updatesChecked,
135
+ capabilities,
136
+ updates: {
137
+ cli: { installed: VERSION, latest, status: updateStatus },
138
+ },
139
+ };
140
+ }
141
+ export function formatDoctor(report) {
142
+ const lines = [`Andesyte doctor (${report.version})`];
143
+ for (const [name, capability] of Object.entries(report.capabilities)) {
144
+ lines.push(`${capability.status.toUpperCase()} ${name}: ${capability.detail}${capability.docs ? ` — ${capability.docs}` : ""}`);
145
+ }
146
+ const update = report.updates.cli;
147
+ if (!report.updates_checked)
148
+ lines.push("Updates: not checked. Run `andesyte doctor --check-updates`.");
149
+ else if (update.status === "available")
150
+ lines.push(`Update available: ${update.installed} -> ${update.latest}`);
151
+ else if (update.status === "unavailable")
152
+ lines.push(`Update check unavailable; installed CLI ${update.installed}.`);
153
+ else
154
+ lines.push(`CLI version: ${update.installed} is current.`);
155
+ return `${lines.join("\n")}\n`;
156
+ }
package/dist/format.js CHANGED
@@ -6,9 +6,10 @@ function describeFinding(f) {
6
6
  const cwe = f.cwe ? ` [${f.cwe}]` : "";
7
7
  return ` ${f.severity.toUpperCase()} ${f.path}:${f.start_line}${cwe}\n ${f.id} — ${f.message.trim()}`;
8
8
  }
9
- const fix = f.fixed_in ? ` — fixed in ${f.fixed_in}` : " — no fix published";
9
+ const fix = f.fixed_in ? ` — fixed in ${f.fixed_in}` : " — fix unknown; inspect advisory";
10
10
  const id = f.cve ?? f.id;
11
- return ` ${f.severity.toUpperCase()} ${f.package}@${f.version} (${f.ecosystem})\n ${id}${fix}\n ${f.summary}`;
11
+ const severity = f.severity_known === false ? "UNKNOWN" : f.severity.toUpperCase();
12
+ return ` ${severity} ${f.package}@${f.version} (${f.ecosystem})\n ${id}${fix}\n ${f.summary}`;
12
13
  }
13
14
  /**
14
15
  * Human output always states coverage, because an empty finding list is only
@@ -17,6 +18,14 @@ function describeFinding(f) {
17
18
  export function formatHuman(result) {
18
19
  const lines = [];
19
20
  const { coverage } = result;
21
+ if (result.scope) {
22
+ lines.push(`scope: ${result.scope.selection}, content: ${result.scope.content}`);
23
+ if (result.scope.empty_reason)
24
+ lines.push(result.scope.empty_reason);
25
+ }
26
+ if (result.suppression?.suppressed) {
27
+ lines.push(`${result.suppression.suppressed} finding(s) accepted by project suppression policy.`);
28
+ }
20
29
  if (result.findings.length > 0) {
21
30
  lines.push(`${result.findings.length} finding(s):`, "");
22
31
  for (const f of result.findings)
@@ -32,6 +41,13 @@ export function formatHuman(result) {
32
41
  }
33
42
  const summary = [...grouped.entries()].map(([r, n]) => `${r}: ${n}`).join(", ");
34
43
  lines.push(`skipped: ${summary}`);
44
+ // `cap_reached` is the one skip reason the user can directly act on, and
45
+ // the count alone gives no hint that a flag controls it. Without this a
46
+ // first run on a large repo reads as an unexplained partial scan.
47
+ const capped = grouped.get("cap_reached");
48
+ if (capped) {
49
+ lines.push(` → ${capped} file(s) exceeded the --max-files cap; re-run with a higher --max-files or narrow the scope with --path to cover them.`);
50
+ }
35
51
  }
36
52
  for (const e of result.errors) {
37
53
  lines.push(`error [${e.code}]: ${e.message}`);
@@ -44,7 +60,9 @@ export function formatHuman(result) {
44
60
  }
45
61
  else if (result.findings.length === 0 && result.status === "complete") {
46
62
  lines.push("");
47
- lines.push("No findings in the scanned scope.");
63
+ lines.push(result.suppression?.suppressed
64
+ ? "No unsuppressed findings in the scanned scope."
65
+ : "No findings in the scanned scope.");
48
66
  }
49
67
  return `${lines.join("\n")}\n`;
50
68
  }
@@ -0,0 +1,19 @@
1
+ export declare class GitHubPullRequestError extends Error {
2
+ constructor(message: string);
3
+ }
4
+ export interface GitHubPullRequest {
5
+ number: number;
6
+ url: string;
7
+ headOid: string;
8
+ baseOid: string;
9
+ }
10
+ /** Validates the bounded, structured fields requested from the local gh CLI. */
11
+ export declare function parseGitHubPullRequest(raw: string, requestedNumber: number): GitHubPullRequest;
12
+ /**
13
+ * Uses the local gh session to resolve a GitHub PR, fetches immutable commits
14
+ * through the repository's existing origin, and removes its detached worktree
15
+ * once the callback settles. It never changes the caller's checkout.
16
+ */
17
+ export declare function withGitHubPullRequest<T>(root: string, number: number, callback: (target: GitHubPullRequest & {
18
+ root: string;
19
+ }) => Promise<T>): Promise<T>;