Skip to content

API.en.md

Latest commit

 

History

History
141 lines (110 loc) · 5.68 KB

API.en.md

File metadata and controls

141 lines (110 loc) · 5.68 KB
Raw

API reference

Overview · 中文 API · Report schema · Snapshot schema

The package is not published to the npm registry yet. The binary syntax and package-name imports below describe the installed package contract; use the source-checkout commands in the overview until registry publication.

CLI

agent-instruction-stack-resolver scan <repo> [options]
agent-instruction-stack-resolver resolve <repo> <path> [options]
agent-instruction-stack-resolver reach <repo> <instruction-file> [options]
agent-instruction-stack-resolver snapshot <repo> [--output <snapshot.json>] [options]
agent-instruction-stack-resolver diff <repo> --baseline <snapshot.json> [options]
agent-instruction-stack-resolver impact <repo> <instruction-file> --baseline <snapshot.json> [options]
agent-instruction-stack-resolver coverage <repo> [options]
agent-instruction-stack-resolver conflicts <repo> [options]

Command results

Command Mode-specific result
scan Complete inventory, scan state, settings references, coverage, conflicts, and findings.
resolve resolve: contained target state, statically applicable instruction set, and stack signature.
reach reach: current source existence and affected content paths.
snapshot Raw ResolverSnapshot JSON; no report wrapper. Not created for incomplete scans.
diff diff: source add/remove/change and content-path stack-signature deltas.
impact impact plus diff: source change classification and gained/lost/changed path membership.
coverage Report filtered to coverage/scope/scanner findings.
conflicts Report filtered to instruction-conflict-* findings.

Options

  • --format markdown|json|junit|sarif
  • --json, --junit, --sarif
  • --fail-on low|medium|high|critical|none — full-set gate, default high
  • --min-severity low|medium|high|critical — presentation filter, default low
  • --max-findings <positive-integer> — presentation limit only
  • --profile vscode-copilot-static|portable-agents-md|inventory
  • --baseline <snapshot.json> — required by diff and impact
  • --output <new-file> — creates a new file instead of printing; existing targets and symlink/reparse parent components are rejected
  • --quiet
  • --max-depth <n>
  • --max-directories <n>
  • --max-files <n>
  • --max-directory-entries <n>
  • --max-file-bytes <n>
  • --max-source-bytes <n>
  • --max-total-bytes <n>
  • --max-diagnostics <n>
  • --max-analysis-operations <n>
  • --max-snapshot-bytes <n> — canonical pretty snapshot JSON bytes, including the trailing newline; hard maximum 16 MiB
  • --max-snapshot-stack-source-ids <n> — total source ID memberships across all path stacks; hard maximum 1,000,000
  • --version, --help

Exit codes

Code Meaning
0 Complete scan and no finding met the failure threshold.
1 Complete scan and at least one finding met the threshold.
2 Any caught CLI, runtime, filesystem, output, JSON parse, malformed snapshot, or incompatible baseline error.
3 Incomplete scan. The conclusion is fail-closed and no snapshot is created.

Baseline compatibility

diff and impact require the same snapshot kind, schema version, tool version, scanner revision, complete scanner state, profile reference, and scan limits. Baselines are bounded regular files; symlinks and special files are rejected. Production and parsing share the declared snapshot byte/membership limits and hard maxima; the loader also validates exact keys, bounded scalars, normalized safe paths, deterministic ordering, source IDs, revision hashes, stack signatures, and the snapshot fingerprint.

Fingerprint validation detects malformed or modified input. It is not a digital signature or a trust boundary.

Package-root library API

Only four runtime symbols are exported:

  • inspectRepository
  • renderReport
  • VERSION
  • SCHEMA_VERSION

Supporting public TypeScript types are exported from the package root. Scanners, parsers, profile helpers, matching helpers, snapshot validators, and internal raw-body DTOs are not package-root runtime APIs.

inspectRepository

function inspectRepository(
	root: string,
	mode?: ReportMode,
	targetPath?: string,
	options?: InspectOptions
): Promise<ResolverReport>;

targetPath is required when mode is resolve, reach, or impact; the promise rejects with a stable <mode>-requires-target-path error when omitted.

Example:

import {
	SCHEMA_VERSION,
	VERSION,
	inspectRepository,
	renderReport,
	type ResolverSnapshot
} from "agent-instruction-stack-resolver";

const baselineReport = await inspectRepository(
	"examples/impact-before",
	"snapshot",
	undefined,
	{ profile: "vscode-copilot-static", failOn: "none" }
);

if (!baselineReport.snapshot) {
	throw new Error("Baseline scan was incomplete");
}

const baseline: ResolverSnapshot = baselineReport.snapshot;
const impactReport = await inspectRepository(
	"examples/impact-after",
	"impact",
	".github/instructions/review-contract.instructions.md",
	{ profile: "vscode-copilot-static", failOn: "none", baseline }
);

console.log(VERSION, SCHEMA_VERSION);
process.stdout.write(renderReport(impactReport, "json"));

renderReport

function renderReport(report: ResolverReport, format: OutputFormat): string;

The JSON format serializes only the public report DTO. All formats omit instruction bodies and local absolute scan roots. Paths and hashes remain public report metadata.

Schemas