@oh-my-pi/pi-coding-agent 17.2.0 → 17.2.1

package/src/security/comparison.ts

@@ -0,0 +1,255 @@
+import type { SecurityComparisonReport, SecurityFinding, SecurityFindingMatch, SecurityScanBundle } from "./contracts";
+
+export interface SecurityDifferentialFindingMatch {
+	referenceFindingId: string;
+	candidateFindingId: string;
+	basis: "fingerprint" | "rule_location" | "taxonomy_location";
+}
+export interface SecurityDifferentialFindingSummary {
+	findingId: string;
+	ruleId: string;
+	title: string;
+	severity: SecurityFinding["severity"]["level"];
+	confidence: SecurityFinding["confidence"]["level"];
+	validationStatus: SecurityFinding["validation"]["status"];
+	dispositionStatus: SecurityFinding["disposition"]["status"];
+	primaryLocation?: { path: string; startLine: number };
+}
+
+export interface SecurityDifferentialScanSummary {
+	scanId: string;
+	producer: SecurityScanBundle["scan"]["producer"];
+	status: SecurityScanBundle["scan"]["status"];
+	findingCount: number;
+	actionableFindingCount: number;
+	validatedFindingCount: number;
+	rejectedFindingCount: number;
+	coverage: SecurityScanBundle["scan"]["coverage"];
+	metrics?: SecurityScanBundle["scan"]["metrics"];
+}
+
+export interface SecurityDifferentialReport {
+	referenceScanId: string;
+	candidateScanId: string;
+	matches: SecurityDifferentialFindingMatch[];
+	referenceOnlyFindingIds: string[];
+	candidateOnlyFindingIds: string[];
+	reference: SecurityDifferentialScanSummary;
+	candidate: SecurityDifferentialScanSummary;
+	referenceOnlyFindings: SecurityDifferentialFindingSummary[];
+	candidateOnlyFindings: SecurityDifferentialFindingSummary[];
+	referenceFindingCount: number;
+	candidateFindingCount: number;
+	matchedFindingCount: number;
+	recallAgainstReference: number;
+	precisionAgainstReference: number;
+	jaccardOverlap: number;
+}
+
+function normalizedPrimaryLocation(finding: SecurityFinding): string | undefined {
+	const location = finding.occurrences.flatMap(occurrence => occurrence.locations)[0];
+	if (!location) return undefined;
+	return `${location.path.replaceAll("\\", "/").replace(/^\.\//, "").toLowerCase()}:${location.startLine}`;
+}
+
+function fallbackKey(finding: SecurityFinding): string | undefined {
+	const location = normalizedPrimaryLocation(finding);
+	if (!location) return undefined;
+	return `${finding.ruleId.trim().toLowerCase()}\u0000${location}`;
+}
+
+function normalizedPath(value: string): string {
+	return value.replaceAll("\\", "/").replace(/^\.\//, "").toLowerCase();
+}
+
+function findingLocations(finding: SecurityFinding) {
+	return finding.occurrences.flatMap(occurrence => occurrence.locations);
+}
+
+function taxonomyLocationMatch(reference: SecurityFinding, candidate: SecurityFinding): boolean {
+	const referenceCwes = new Set(reference.taxonomy.cwe.map(value => value.trim().toUpperCase()));
+	if (
+		referenceCwes.size === 0 ||
+		!candidate.taxonomy.cwe.some(value => referenceCwes.has(value.trim().toUpperCase()))
+	) {
+		return false;
+	}
+	for (const referenceLocation of findingLocations(reference)) {
+		for (const candidateLocation of findingLocations(candidate)) {
+			if (normalizedPath(referenceLocation.path) !== normalizedPath(candidateLocation.path)) continue;
+			const referenceEnd = referenceLocation.endLine ?? referenceLocation.startLine;
+			const candidateEnd = candidateLocation.endLine ?? candidateLocation.startLine;
+			if (
+				Math.max(referenceLocation.startLine, candidateLocation.startLine) <=
+					Math.min(referenceEnd, candidateEnd) ||
+				Math.abs(referenceLocation.startLine - candidateLocation.startLine) <= 3
+			) {
+				return true;
+			}
+		}
+	}
+	return false;
+}
+
+function findingSummary(finding: SecurityFinding): SecurityDifferentialFindingSummary {
+	const location = finding.occurrences.flatMap(occurrence => occurrence.locations)[0];
+	return {
+		findingId: finding.id,
+		ruleId: finding.ruleId,
+		title: finding.title,
+		severity: finding.severity.level,
+		confidence: finding.confidence.level,
+		validationStatus: finding.validation.status,
+		dispositionStatus: finding.disposition.status,
+		...(location ? { primaryLocation: { path: location.path, startLine: location.startLine } } : {}),
+	};
+}
+
+function scanSummary(bundle: SecurityScanBundle): SecurityDifferentialScanSummary {
+	return {
+		scanId: bundle.scan.id,
+		producer: bundle.scan.producer,
+		status: bundle.scan.status,
+		findingCount: bundle.findings.length,
+		actionableFindingCount: bundle.findings.filter(finding => finding.disposition.status === "open").length,
+		validatedFindingCount: bundle.findings.filter(finding => finding.validation.status === "validated").length,
+		rejectedFindingCount: bundle.findings.filter(finding => finding.validation.status === "rejected").length,
+		coverage: bundle.scan.coverage,
+		...(bundle.scan.metrics ? { metrics: bundle.scan.metrics } : {}),
+	};
+}
+
+function ratio(numerator: number, denominator: number): number {
+	return denominator === 0 ? (numerator === 0 ? 1 : 0) : numerator / denominator;
+}
+
+export function compareSecurityProducers(
+	reference: SecurityScanBundle,
+	candidate: SecurityScanBundle,
+): SecurityDifferentialReport {
+	const candidateByFingerprint = new Map(candidate.findings.map(finding => [finding.fingerprint, finding]));
+	const candidateByFallback = new Map<string, SecurityFinding[]>();
+	for (const finding of candidate.findings) {
+		const key = fallbackKey(finding);
+		if (!key) continue;
+		const bucket = candidateByFallback.get(key) ?? [];
+		bucket.push(finding);
+		candidateByFallback.set(key, bucket);
+	}
+	const usedCandidateIds = new Set<string>();
+	const matchedReferenceIds = new Set<string>();
+	const matches: SecurityDifferentialFindingMatch[] = [];
+	const addMatch = (
+		referenceFinding: SecurityFinding,
+		candidateFinding: SecurityFinding,
+		basis: SecurityDifferentialFindingMatch["basis"],
+	) => {
+		matchedReferenceIds.add(referenceFinding.id);
+		usedCandidateIds.add(candidateFinding.id);
+		matches.push({
+			referenceFindingId: referenceFinding.id,
+			candidateFindingId: candidateFinding.id,
+			basis,
+		});
+	};
+	for (const referenceFinding of reference.findings) {
+		const exact = candidateByFingerprint.get(referenceFinding.fingerprint);
+		if (exact && !usedCandidateIds.has(exact.id)) addMatch(referenceFinding, exact, "fingerprint");
+	}
+	for (const referenceFinding of reference.findings) {
+		if (matchedReferenceIds.has(referenceFinding.id)) continue;
+		const key = fallbackKey(referenceFinding);
+		const fallback = key
+			? candidateByFallback.get(key)?.find(finding => !usedCandidateIds.has(finding.id))
+			: undefined;
+		if (fallback) addMatch(referenceFinding, fallback, "rule_location");
+	}
+	const unmatchedReferences = reference.findings.filter(finding => !matchedReferenceIds.has(finding.id));
+	for (const referenceFinding of unmatchedReferences) {
+		const compatibleCandidates = candidate.findings.filter(
+			finding => !usedCandidateIds.has(finding.id) && taxonomyLocationMatch(referenceFinding, finding),
+		);
+		if (compatibleCandidates.length !== 1) continue;
+		const compatibleCandidate = compatibleCandidates[0];
+		const compatibleReferences = unmatchedReferences.filter(
+			finding => !matchedReferenceIds.has(finding.id) && taxonomyLocationMatch(finding, compatibleCandidate),
+		);
+		if (compatibleReferences.length !== 1) continue;
+		addMatch(referenceFinding, compatibleCandidate, "taxonomy_location");
+	}
+	const referenceOnlyFindingIds = reference.findings
+		.filter(finding => !matchedReferenceIds.has(finding.id))
+		.map(finding => finding.id);
+	const candidateOnlyFindingIds = candidate.findings
+		.filter(finding => !usedCandidateIds.has(finding.id))
+		.map(finding => finding.id);
+	const unionSize = reference.findings.length + candidate.findings.length - matches.length;
+	return {
+		referenceScanId: reference.scan.id,
+		candidateScanId: candidate.scan.id,
+		matches,
+		referenceOnlyFindingIds,
+		reference: scanSummary(reference),
+		candidate: scanSummary(candidate),
+		referenceOnlyFindings: referenceOnlyFindingIds.map(findingId =>
+			findingSummary(reference.findings.find(finding => finding.id === findingId)!),
+		),
+		candidateOnlyFindings: candidateOnlyFindingIds.map(findingId =>
+			findingSummary(candidate.findings.find(finding => finding.id === findingId)!),
+		),
+		candidateOnlyFindingIds,
+		referenceFindingCount: reference.findings.length,
+		candidateFindingCount: candidate.findings.length,
+		matchedFindingCount: matches.length,
+		recallAgainstReference: ratio(matches.length, reference.findings.length),
+		precisionAgainstReference: ratio(matches.length, candidate.findings.length),
+		jaccardOverlap: ratio(matches.length, unionSize),
+	};
+}
+
+export function compareSecurityLineage(
+	before: SecurityScanBundle,
+	after: SecurityScanBundle,
+): SecurityComparisonReport {
+	// An incomplete after-scan proves nothing about unmatched earlier findings;
+	// claiming them "resolved" against a cancelled/partial/failed run would be a lie.
+	if (after.scan.status !== "completed") {
+		throw new Error(
+			`Security lineage comparison requires a completed after-scan; ${after.scan.id} is ${after.scan.status}`,
+		);
+	}
+	const differential = compareSecurityProducers(before, after);
+	const beforeById = new Map(before.findings.map(finding => [finding.id, finding]));
+	const afterById = new Map(after.findings.map(finding => [finding.id, finding]));
+	const matches: SecurityFindingMatch[] = differential.matches.map(match => {
+		const beforeFinding = beforeById.get(match.referenceFindingId);
+		const afterFinding = afterById.get(match.candidateFindingId);
+		if (!beforeFinding || !afterFinding) throw new Error("Security comparison produced an invalid finding reference");
+		return {
+			beforeFindingId: beforeFinding.id,
+			afterFindingId: afterFinding.id,
+			fingerprint: beforeFinding.fingerprint,
+			status: "unchanged",
+			matchBasis: match.basis,
+		};
+	});
+	for (const findingId of differential.referenceOnlyFindingIds) {
+		const finding = beforeById.get(findingId);
+		if (!finding) continue;
+		matches.push({ beforeFindingId: finding.id, fingerprint: finding.fingerprint, status: "resolved" });
+	}
+	for (const findingId of differential.candidateOnlyFindingIds) {
+		const finding = afterById.get(findingId);
+		if (!finding) continue;
+		matches.push({ afterFindingId: finding.id, fingerprint: finding.fingerprint, status: "new" });
+	}
+	matches.sort((left, right) => left.fingerprint.localeCompare(right.fingerprint));
+	return {
+		beforeScanId: before.scan.id,
+		afterScanId: after.scan.id,
+		matches,
+		unchanged: matches.filter(match => match.status === "unchanged").length,
+		introduced: matches.filter(match => match.status === "new").length,
+		resolved: matches.filter(match => match.status === "resolved").length,
+	};
+}

package/src/security/contracts/ids.ts

@@ -0,0 +1,111 @@
+import type { SecurityLocation } from "./types";
+
+function canonicalize(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (!value || typeof value !== "object") return value;
+	const record = value as Record<string, unknown>;
+	const result: Record<string, unknown> = {};
+	for (const key of Object.keys(record).sort()) {
+		const item = record[key];
+		if (item !== undefined) result[key] = canonicalize(item);
+	}
+	return result;
+}
+
+export function canonicalSecurityJson(value: unknown): string {
+	return JSON.stringify(canonicalize(value));
+}
+
+function normalizeFingerprintPath(value: string): string {
+	return value.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+function compareNormalizedLocationValues(
+	left: string | number | undefined,
+	right: string | number | undefined,
+): number {
+	if (left === right) return 0;
+	if (left === undefined) return -1;
+	if (right === undefined) return 1;
+	if (typeof left === "number" && typeof right === "number") {
+		const leftNaN = Number.isNaN(left);
+		const rightNaN = Number.isNaN(right);
+		if (leftNaN || rightNaN) return leftNaN ? (rightNaN ? 0 : -1) : 1;
+		return left - right;
+	}
+	return String(left) < String(right) ? -1 : 1;
+}
+
+const NORMALIZED_LOCATION_SORT_KEYS = ["path", "startLine", "endLine", "startColumn", "endColumn", "role"] as const;
+
+function normalizedLocations(
+	locations: readonly SecurityLocation[],
+): Array<Record<string, string | number | undefined>> {
+	return locations
+		.map(location => ({
+			path: normalizeFingerprintPath(location.path),
+			startLine: location.startLine,
+			endLine: location.endLine,
+			startColumn: location.startColumn,
+			endColumn: location.endColumn,
+			role: location.role,
+		}))
+		.sort((left, right) => {
+			for (const key of NORMALIZED_LOCATION_SORT_KEYS) {
+				const comparison = compareNormalizedLocationValues(left[key], right[key]);
+				if (comparison !== 0) return comparison;
+			}
+			return 0;
+		});
+}
+
+export interface SecurityFindingFingerprintInput {
+	ruleId: string;
+	category: string;
+	anchor?: string;
+	locations: readonly SecurityLocation[];
+}
+
+export function createSecurityFindingFingerprint(input: SecurityFindingFingerprintInput): string {
+	const digest = Bun.SHA256.hash(
+		canonicalSecurityJson({
+			ruleId: input.ruleId.trim().toLowerCase(),
+			category: input.category.trim().toLowerCase(),
+			anchor: input.anchor?.trim().toLowerCase() || undefined,
+			locations: normalizedLocations(input.locations),
+		}),
+		"hex",
+	);
+	return `omp-security/v1:sha256:${digest}`;
+}
+
+export function createSecurityFindingId(fingerprint: string): string {
+	return `secf_${Bun.SHA256.hash(fingerprint, "hex").slice(0, 24)}`;
+}
+
+export function createSecurityOccurrenceId(fingerprint: string, locations: readonly SecurityLocation[]): string {
+	const material = canonicalSecurityJson({ fingerprint, locations: normalizedLocations(locations) });
+	return `seco_${Bun.SHA256.hash(material, "hex").slice(0, 24)}`;
+}
+
+export function createSecurityEvidenceId(fingerprint: string, label: string, ordinal: number): string {
+	return `sece_${Bun.SHA256.hash(canonicalSecurityJson({ fingerprint, label, ordinal }), "hex").slice(0, 24)}`;
+}
+
+export function createSecurityScanId(randomUuid: () => string = () => Bun.randomUUIDv7()): string {
+	return `secscan_${randomUuid().replaceAll("-", "")}`;
+}
+
+export function createSecurityPlanId(fingerprint: string): string {
+	return `secplan_${Bun.SHA256.hash(fingerprint, "hex").slice(0, 24)}`;
+}
+
+export function encodeSecurityProjectKey(repositoryRoot: string): string {
+	const normalized = repositoryRoot.replaceAll("\\", "/").replace(/\/$/, "");
+	const readable = normalized
+		.replace(/^\//, "")
+		.replace(/[^a-zA-Z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(-80);
+	return `${readable || "project"}-${Bun.SHA256.hash(normalized, "hex").slice(0, 12)}`;
+}

package/src/security/contracts/index.ts

@@ -0,0 +1,4 @@
+export * from "./ids";
+export * from "./schemas";
+export * from "./types";
+export * from "./validation";

package/src/security/contracts/schemas.ts

@@ -0,0 +1,201 @@
+import { type } from "arktype";
+
+const stringRecordSchema = type({ "[string]": "string" });
+const unknownRecordSchema = type({ "[string]": "unknown" });
+
+export const securityProducerSchema = type({
+	kind: "'omp-native' | 'codex-security-bundle' | 'codex-security-cloud' | 'sarif-import'",
+	name: "string > 0",
+	"version?": "string",
+	"vendor?": "string",
+	"revision?": "string",
+	"pluginVersion?": "string",
+});
+
+export const securityProvenanceSchema = type({
+	producer: securityProducerSchema,
+	createdAt: "string > 0",
+	"importedAt?": "string",
+	"sourceIds?": stringRecordSchema,
+	"vendorFingerprints?": stringRecordSchema,
+	"upstream?": {
+		"repository?": "string",
+		"revision?": "string",
+		"packageVersion?": "string",
+		"pluginVersion?": "string",
+		"archiveSha256?": "string",
+	},
+	"metadata?": unknownRecordSchema,
+});
+
+export const securityLocationSchema = type({
+	path: "string > 0",
+	startLine: "number.integer >= 1",
+	"endLine?": "number.integer >= 1",
+	"startColumn?": "number.integer >= 1",
+	"endColumn?": "number.integer >= 1",
+	"role?": "string",
+});
+
+export const securityEvidenceSchema = type({
+	id: "string > 0",
+	kind: "'code' | 'trace' | 'validation' | 'note'",
+	label: "string > 0",
+	explanation: "string",
+	"location?": securityLocationSchema,
+	"excerpt?": "string",
+});
+
+export const securityOccurrenceSchema = type({
+	id: "string > 0",
+	locations: securityLocationSchema.array().atLeastLength(1),
+	evidenceIds: "string[]",
+});
+
+export const securityFindingSchema = type({
+	id: "string > 0",
+	scanId: "string > 0",
+	fingerprint: "string > 0",
+	ruleId: "string > 0",
+	"anchor?": "string",
+	title: "string > 0",
+	summary: "string",
+	severity: {
+		level: "'critical' | 'high' | 'medium' | 'low' | 'informational'",
+		"score?": "number",
+		"scoringSystem?": "string",
+		"vector?": "string",
+		"rationale?": "string",
+	},
+	confidence: {
+		level: "'high' | 'medium' | 'low'",
+		"rationale?": "string",
+	},
+	taxonomy: {
+		category: "string > 0",
+		cwe: "string[]",
+		"tags?": "string[]",
+	},
+	occurrences: securityOccurrenceSchema.array().atLeastLength(1),
+	evidence: securityEvidenceSchema.array(),
+	"remediation?": "string",
+	validation: {
+		status: "'unvalidated' | 'validated' | 'rejected' | 'partial' | 'error'",
+		"summary?": "string",
+		evidenceIds: "string[]",
+		"validatedAt?": "string",
+	},
+	disposition: {
+		status: "'open' | 'false_positive' | 'accepted_risk' | 'fixed' | 'wont_fix'",
+		"rationale?": "string",
+		"updatedAt?": "string",
+		"actor?": "string",
+	},
+	provenance: securityProvenanceSchema,
+	"extensions?": unknownRecordSchema,
+});
+
+export const securityCoverageSchema = type({
+	mode: "'repository' | 'scoped_path' | 'diff' | 'working_tree' | 'deep_repository' | 'imported'",
+	completeness: "'complete' | 'partial' | 'unknown'",
+	inventoryStrategy: "'repository' | 'scoped_path' | 'diff' | 'directory' | 'custom' | 'imported'",
+	includePaths: "string[]",
+	excludePaths: "string[]",
+	surfaces: type({
+		id: "string > 0",
+		label: "string > 0",
+		disposition: "'reported' | 'no_issue_found' | 'rejected' | 'not_applicable' | 'needs_follow_up'",
+		receiptRefs: "string[]",
+		"riskArea?": "string",
+		"notes?": "string",
+	}).array(),
+	explicitExclusions: type({ pattern: "string", reason: "string" }).array(),
+	deferred: type({
+		id: "string > 0",
+		reason: "string > 0",
+		"paths?": "string[]",
+		"surfaceIds?": "string[]",
+	}).array(),
+	"openQuestions?": type({ question: "string > 0", "followUpPrompt?": "string" }).array(),
+});
+
+export const securityTargetSchema = type({
+	kind: "'repository' | 'scoped_path' | 'ref_diff' | 'working_tree' | 'imported'",
+	repositoryRoot: "string > 0",
+	displayName: "string > 0",
+	"revision?": "string",
+	"baseRevision?": "string",
+	"headRevision?": "string",
+	includePaths: "string[]",
+	excludePaths: "string[]",
+	treeDigest: "string > 0",
+});
+
+export const securityScanPlanSchema = type({
+	documentType: "'omp-security.scan-plan'",
+	schemaVersion: "'1.0'",
+	id: "string > 0",
+	createdAt: "string > 0",
+	repositoryRoot: "string > 0",
+	target: securityTargetSchema,
+	knowledgeBases: type({ path: "string > 0", sha256: "string > 0", size: "number.integer >= 0" }).array(),
+	output: {
+		root: "string > 0",
+		archiveExisting: "boolean",
+		existingState: "'absent' | 'empty' | 'archivable'",
+	},
+	model: { provider: "string > 0", modelId: "string > 0", "thinkingLevel?": "string" },
+	account: {
+		provider: "string > 0",
+		credentialId: "number.integer >= 1",
+		"accountId?": "string",
+		"email?": "string",
+		"organizationId?": "string",
+		"organizationName?": "string",
+	},
+	configFingerprint: "string > 0",
+	workflowFingerprint: "string > 0",
+	fingerprint: "string > 0",
+});
+
+export const securityScanMetricsSchema = type({
+	"runtimeMs?": "number >= 0",
+	"tokenUsage?": {
+		input: "number >= 0",
+		output: "number >= 0",
+		reasoning: "number >= 0",
+		cacheRead: "number >= 0",
+		cacheWrite: "number >= 0",
+		total: "number >= 0",
+	},
+	"cost?": "number >= 0",
+	"premiumRequests?": "number >= 0",
+});
+
+export const securityScanSchema = type({
+	documentType: "'omp-security.scan'",
+	schemaVersion: "'1.0'",
+	id: "string > 0",
+	projectKey: "string > 0",
+	status: "'planned' | 'running' | 'completed' | 'partial' | 'cancelled' | 'failed'",
+	createdAt: "string > 0",
+	"startedAt?": "string",
+	"completedAt?": "string",
+	"plan?": securityScanPlanSchema,
+	target: securityTargetSchema,
+	producer: securityProducerSchema,
+	provenance: securityProvenanceSchema,
+	findingIds: "string[]",
+	coverage: securityCoverageSchema,
+	"reportRef?": "string",
+	"sarifRef?": "string",
+	"error?": "string",
+	"metrics?": securityScanMetricsSchema,
+});
+
+export const securityScanBundleSchema = type({
+	scan: securityScanSchema,
+	findings: securityFindingSchema.array(),
+	"report?": "string",
+	"sarif?": unknownRecordSchema,
+});