@voltro/plan 0.85.0 → 0.87.0

package/THIRD-PARTY-NOTICES.md

@@ -1,6 +1,6 @@
 # Third-Party Notices — @voltro/plan
 
-This package depends on the open-source software listed below. Each is the
+This package uses the open-source software listed below. Each is the
 property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/plan itself, which is proprietary (see LICENSE).

package/dist/canonical.js

@@ -0,0 +1,118 @@
+//#region src/canonical.ts
+var e = (e) => JSON.stringify(t(e)), t = (e) => {
+	if (Array.isArray(e)) return e.map(t);
+	if (typeof e == "object" && e) {
+		let n = {};
+		for (let r of Object.keys(e).sort()) {
+			let i = e[r];
+			i !== void 0 && (n[r] = t(i));
+		}
+		return n;
+	}
+	return e;
+}, n = new Uint32Array([
+	1116352408,
+	1899447441,
+	3049323471,
+	3921009573,
+	961987163,
+	1508970993,
+	2453635748,
+	2870763221,
+	3624381080,
+	310598401,
+	607225278,
+	1426881987,
+	1925078388,
+	2162078206,
+	2614888103,
+	3248222580,
+	3835390401,
+	4022224774,
+	264347078,
+	604807628,
+	770255983,
+	1249150122,
+	1555081692,
+	1996064986,
+	2554220882,
+	2821834349,
+	2952996808,
+	3210313671,
+	3336571891,
+	3584528711,
+	113926993,
+	338241895,
+	666307205,
+	773529912,
+	1294757372,
+	1396182291,
+	1695183700,
+	1986661051,
+	2177026350,
+	2456956037,
+	2730485921,
+	2820302411,
+	3259730800,
+	3345764771,
+	3516065817,
+	3600352804,
+	4094571909,
+	275423344,
+	430227734,
+	506948616,
+	659060556,
+	883997877,
+	958139571,
+	1322822218,
+	1537002063,
+	1747873779,
+	1955562222,
+	2024104815,
+	2227730452,
+	2361852424,
+	2428436474,
+	2756734187,
+	3204031479,
+	3329325298
+]), r = (e) => {
+	let t = new TextEncoder().encode(e), r = t.length * 8, i = new Uint8Array(t.length + 9 + 63 >> 6 << 6);
+	i.set(t), i[t.length] = 128;
+	let a = new DataView(i.buffer);
+	a.setUint32(i.length - 8, Math.floor(r / 4294967296)), a.setUint32(i.length - 4, r >>> 0);
+	let o = new Uint32Array([
+		1779033703,
+		3144134277,
+		1013904242,
+		2773480762,
+		1359893119,
+		2600822924,
+		528734635,
+		1541459225
+	]), s = /* @__PURE__ */ new Uint32Array(64), c = (e, t) => e >>> t | e << 32 - t;
+	for (let e = 0; e < i.length; e += 64) {
+		for (let t = 0; t < 16; t++) s[t] = a.getUint32(e + t * 4);
+		for (let e = 16; e < 64; e++) {
+			let t = c(s[e - 15], 7) ^ c(s[e - 15], 18) ^ s[e - 15] >>> 3, n = c(s[e - 2], 17) ^ c(s[e - 2], 19) ^ s[e - 2] >>> 10;
+			s[e] = s[e - 16] + t + s[e - 7] + n >>> 0;
+		}
+		let [t, r, i, l, u, d, f, p] = [
+			o[0],
+			o[1],
+			o[2],
+			o[3],
+			o[4],
+			o[5],
+			o[6],
+			o[7]
+		];
+		for (let e = 0; e < 64; e++) {
+			let a = p + (c(u, 6) ^ c(u, 11) ^ c(u, 25)) + (u & d ^ ~u & f) + n[e] + s[e] >>> 0, o = (c(t, 2) ^ c(t, 13) ^ c(t, 22)) + (t & r ^ t & i ^ r & i) >>> 0;
+			p = f, f = d, d = u, u = l + a >>> 0, l = i, i = r, r = t, t = a + o >>> 0;
+		}
+		o[0] = o[0] + t >>> 0, o[1] = o[1] + r >>> 0, o[2] = o[2] + i >>> 0, o[3] = o[3] + l >>> 0, o[4] = o[4] + u >>> 0, o[5] = o[5] + d >>> 0, o[6] = o[6] + f >>> 0, o[7] = o[7] + p >>> 0;
+	}
+	return [...o].map((e) => e.toString(16).padStart(8, "0")).join("");
+}, i = (t) => `sha256:${r(e(t))}`;
+//#endregion
+export { e as canonicalJson, i as fingerprint, r as sha256Hex };

package/dist/closure.js

@@ -0,0 +1,116 @@
+import { fingerprint as e } from "./canonical.js";
+import { Schema as t } from "effect";
+//#region src/closure.ts
+var n = "voltro-plan-closure/v1", r = t.String.pipe(t.check(t.isMinLength(1))), i = t.String.pipe(t.check(t.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/))), a = t.String.pipe(t.check(t.isPattern(/^sha256:[a-f0-9]{64}$/))), o = (e) => {
+	let o = e.grammar, s = (e) => t.String.pipe(t.check(t.isPattern(e))), c = t.Struct({
+		id: s(o.closureRun),
+		pass: t.Literals(["contract", "adversarial"]),
+		reviewer: r,
+		reviewContext: r,
+		planRevision: a,
+		completedAt: i,
+		findingRefs: t.Array(s(o.finding)),
+		result: t.Literals(["passed", "findings"]),
+		toolVersion: r
+	}), l = t.Struct({
+		id: s(o.certificate),
+		plan: s(o.plan),
+		planRevision: a,
+		workItems: t.Array(s(o.workItem)),
+		evidenceRefs: t.Array(s(o.evidence)),
+		closureRuns: t.Array(s(o.closureRun)).pipe(t.check(t.isBetweenLength(2, 2))),
+		confirmedBy: r,
+		issuedAt: i,
+		toolVersion: r
+	});
+	return t.Struct({
+		schemaVersion: t.Literal(n),
+		plan: s(o.plan),
+		runs: t.Array(c),
+		certificates: t.Array(l)
+	});
+}, s = (t, n, r, i = () => void 0, a = /* @__PURE__ */ new Map()) => {
+	let o = new Set(t.workItems.map((e) => e.id)), s = [...new Set(t.workItems.flatMap((e) => e.dependsOn).filter((e) => !o.has(e)))].sort();
+	return e({
+		instance: t,
+		dependencies: s.map((e) => {
+			let t = i(e);
+			return [e, t === "closed" ? "verified" : t ?? "missing"];
+		}),
+		decisions: [...new Set(t.workItems.flatMap((e) => e.links.adrs))].sort().map((e) => [e, a.get(e) ?? null]),
+		evidence: n.filter((e) => e.subjectRefs.some((e) => o.has(e))).map((e) => e.id).sort(),
+		findings: r.filter((e) => e.targetWorkItems.some((e) => o.has(e))).map((e) => [e.id, e.status]).sort()
+	});
+}, c = (e, t) => {
+	if (e === void 0) return { state: "open" };
+	let n = new Map(e.runs.map((e) => [e.id, e])), r = [...e.certificates].reverse().find((e) => e.planRevision === t && e.closureRuns.every((e) => n.get(e)?.result === "passed" && n.get(e)?.planRevision === t));
+	if (r !== void 0) return {
+		state: "certified",
+		certificate: r
+	};
+	let i = [...e.runs].reverse().find((e) => e.pass === "contract" && e.result === "passed" && e.planRevision === t);
+	return i === void 0 ? { state: "open" } : {
+		state: "closure-1",
+		run: i
+	};
+}, l = (e, t, n, r) => ({
+	outcome: "refused",
+	diagnostic: {
+		ruleId: e,
+		severity: "error",
+		message: t,
+		locator: { plan: r },
+		related: [],
+		nextAction: n
+	}
+}), u = (e, t) => `${e}${String(Math.max(0, ...t.filter((t) => t.startsWith(e)).map((t) => Number(t.slice(e.length)))) + 1).padStart(3, "0")}`, d = (e, t, r, i, a, o, s, c) => {
+	let d = t.plan.id, f = t.workItems.filter((e) => e.mandatory && e.supersededBy === void 0), p = f.filter((e) => a(e.id) !== "verified" && a(e.id) !== "closed");
+	if (c.findings.length === 0 && p.length > 0) return l("closure/unverified-items", `${p.length} of ${f.length} mandatory items of ${d} are not verified (${p.slice(0, 3).map((e) => e.id).join(", ")}${p.length > 3 ? ", …" : ""})`, "Verify every mandatory item first: voltro plan status, voltro plan evidence add.", d);
+	let m = new Set(t.workItems.map((e) => e.id)), h = s.filter((e) => e.status === "open" && e.targetWorkItems.some((e) => m.has(e)));
+	for (let e of c.findings) if (!h.some((t) => t.id === e)) return l("closure/unknown-finding", `${e} is not an open finding against ${d}`, "Record the finding first, against the items it concerns.", d);
+	if (c.findings.length === 0 && h.length > 0) return l("closure/open-findings", `${h.length} finding(s) against ${d} are open (${h.map((e) => e.id).slice(0, 3).join(", ")})`, "Resolve them or accept the risk; then close again.", d);
+	let g = r?.runs ?? [];
+	if (c.pass === "adversarial" && c.findings.length === 0) {
+		let e = [...g].reverse().find((e) => e.pass === "contract" && e.result === "passed" && e.planRevision === i);
+		if (e === void 0) return l("closure/order", `${d} has no passed contract pass on its current revision`, "Run the contract pass first: voltro plan close <plan> --pass contract.", d);
+		if (e.reviewer === c.reviewer || e.reviewContext === c.reviewContext) return l("closure/same-context", `the adversarial pass needs another reviewer and another context than ${e.id} (${e.reviewer}, ${e.reviewContext})`, "Have someone else audit it, in their own context.", d);
+	}
+	let _ = t.plan.number, v = {
+		id: u(`CLR-${e.prefix}-${_}-`, g.map((e) => e.id)),
+		pass: c.pass,
+		reviewer: c.reviewer,
+		reviewContext: c.reviewContext,
+		planRevision: i,
+		completedAt: c.at,
+		findingRefs: [...c.findings].sort(),
+		result: c.findings.length === 0 ? "passed" : "findings",
+		toolVersion: c.toolVersion
+	}, y = null;
+	if (c.pass === "adversarial" && v.result === "passed") {
+		let t = [...g].reverse().find((e) => e.pass === "contract" && e.result === "passed" && e.planRevision === i);
+		y = {
+			id: u(`CRT-${e.prefix}-${_}-`, (r?.certificates ?? []).map((e) => e.id)),
+			plan: d,
+			planRevision: i,
+			workItems: f.map((e) => e.id).sort(),
+			evidenceRefs: o.filter((e) => e.subjectRefs.some((e) => m.has(e))).map((e) => e.id).sort(),
+			closureRuns: [t.id, v.id],
+			confirmedBy: c.reviewer,
+			issuedAt: c.at,
+			toolVersion: c.toolVersion
+		};
+	}
+	return {
+		outcome: "recorded",
+		file: {
+			schemaVersion: n,
+			plan: d,
+			runs: [...g, v],
+			certificates: [...r?.certificates ?? [], ...y === null ? [] : [y]]
+		},
+		run: v,
+		certificate: y
+	};
+};
+//#endregion
+export { n as CLOSURE_SCHEMA_VERSION, o as closureFileSchema, c as closureState, d as decideClosure, s as planRevision };

package/dist/diagnostics.js

@@ -0,0 +1,8 @@
+//#region src/diagnostics.ts
+var e = {
+	security: 0,
+	error: 1,
+	warning: 2
+}, t = (e, t) => (e ?? "") < (t ?? "") ? -1 : +((e ?? "") > (t ?? "")), n = (n) => [...n].sort((n, r) => e[n.severity] - e[r.severity] || t(n.locator.plan, r.locator.plan) || t(n.locator.workItem, r.locator.workItem) || t(n.ruleId, r.ruleId) || t(n.locator.file, r.locator.file) || t(n.locator.path, r.locator.path) || t(n.message, r.message)), r = (e, t = !1) => e.some((e) => e.severity !== "warning" || t);
+//#endregion
+export { r as blocks, n as sortDiagnostics };

package/dist/envelope.js

@@ -0,0 +1,16 @@
+//#region src/envelope.ts
+var e = "voltro-plan-command/v1", t = (t) => ({
+	schemaVersion: e,
+	...t
+}), n = {
+	ok: 0,
+	failed: 1,
+	usage: 2,
+	input: 3,
+	conflict: 4,
+	provider: 5,
+	security: 6,
+	internal: 70
+};
+//#endregion
+export { e as COMMAND_SCHEMA_VERSION, n as EXIT, t as envelope };

package/dist/evidence.js

@@ -0,0 +1,82 @@
+import { canonicalJson as e } from "./canonical.js";
+import { EVIDENCE_KINDS as t } from "./schema.js";
+import { EXIT as n } from "./envelope.js";
+//#region src/evidence.ts
+var r = (e, t, n, r, i, a) => ({
+	outcome: "refused",
+	exit: a,
+	diagnostic: {
+		ruleId: e,
+		severity: t,
+		message: n,
+		locator: { workItem: i },
+		related: [],
+		nextAction: r
+	}
+}), i = [
+	/-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+	/\b[sr]k_(live|test)_[A-Za-z0-9]{16,}/,
+	/\bgh[pousr]_[A-Za-z0-9]{30,}/,
+	/\bAKIA[0-9A-Z]{16}\b/,
+	/\bxox[abprs]-[A-Za-z0-9-]{10,}/,
+	/\bBearer\s+[A-Za-z0-9._~+/-]{20,}/
+], a = (a, o, s) => {
+	let c = a.items.get(s.workItem)?.item;
+	if (c === void 0) return r("evidence/unknown-target", "error", `${s.workItem} is not a work item of this program`, "Name an existing work item.", s.workItem, n.failed);
+	if ([
+		s.title,
+		s.uri,
+		s.producedBy,
+		s.command ?? "",
+		s.environment ?? ""
+	].some((e) => i.some((t) => t.test(e))) || /^[a-z][a-z0-9+.-]*:\/\/[^/@\s]*:[^/@\s]*@/i.test(s.uri)) return r("security/secret", "security", "the evidence carries a secret or a credential", "Remove it; reference where the result is kept, never a key.", c.id, n.security);
+	if (!t.includes(s.kind)) return r("evidence/kind", "error", `"${s.kind}" is not an evidence kind`, `Use one of: ${t.join(", ")}.`, c.id, n.usage);
+	if (/^http:\/\//i.test(s.uri)) return r("evidence/uri", "error", `${s.uri} is not https`, "Reference evidence over https, git: or a project-relative path.", c.id, n.failed);
+	if (s.uri.startsWith("/") || /^[A-Za-z]:[\\/]/.test(s.uri) || s.uri.split("/").includes("..")) return r("evidence/uri", "error", `${s.uri} is not portable`, "Use a path relative to the project root, or a URL.", c.id, n.failed);
+	let l = [c.id];
+	for (let e of s.proves) {
+		let t = /^[AE][0-9]{2}$/.test(e) ? `${c.id}-${e}` : e, i = c.acceptance.find((e) => e.id === t), a = c.evidenceRequirements.find((e) => e.id === t);
+		if (i === void 0 && a === void 0) return r("evidence/unknown-target", "error", `${t} is not a check or requirement of ${c.id}`, `Name one of ${[...c.acceptance, ...c.evidenceRequirements].map((e) => e.id).join(", ")}.`, c.id, n.failed);
+		if (a !== void 0 && !a.kinds.includes(s.kind)) return r("evidence/wrong-kind", "error", `${a.id} asks for ${a.kinds.join("/")}, not ${s.kind}`, "Add evidence of a kind the requirement names.", c.id, n.failed);
+		l.push(t);
+	}
+	let u = {
+		kind: s.kind,
+		title: s.title,
+		uri: s.uri,
+		result: s.result,
+		subjectRefs: [...new Set(l)],
+		producedBy: s.producedBy,
+		...s.command === void 0 ? {} : { command: s.command },
+		...s.environment === void 0 ? {} : { environment: s.environment },
+		...s.fingerprint === void 0 ? {} : { fingerprint: s.fingerprint }
+	};
+	if (s.idempotencyKey !== void 0) {
+		let t = a.evidence.find((e) => e.idempotencyKey === s.idempotencyKey);
+		if (t !== void 0) {
+			let { id: i, observedAt: a, idempotencyKey: o, ...l } = t;
+			return e(l) === e(u) ? {
+				outcome: "same",
+				evidence: t
+			} : r("evidence/idempotency-conflict", "error", `the key "${s.idempotencyKey}" was used for other evidence (${t.id})`, "Use a new key for new evidence.", c.id, n.conflict);
+		}
+	}
+	let d = `EVD-${c.id}-`, f = 0n;
+	for (let e of a.evidence) {
+		if (!e.id.startsWith(d)) continue;
+		let t = BigInt(e.id.slice(d.length));
+		t > f && (f = t);
+	}
+	let p = String(f + 1n).padStart(3, "0");
+	return o.evidence.test(`${d}${p}`) ? {
+		outcome: "add",
+		evidence: {
+			id: `${d}${p}`,
+			...u,
+			observedAt: s.observedAt,
+			...s.idempotencyKey === void 0 ? {} : { idempotencyKey: s.idempotencyKey }
+		}
+	} : r("evidence/identifier", "error", `${c.id} cannot form a valid evidence identifier`, "Check the program identifier grammar.", c.id, n.failed);
+};
+//#endregion
+export { a as decideEvidence };

package/dist/ids.js

@@ -0,0 +1,25 @@
+//#region src/ids.ts
+var e = /^[A-Z][A-Z0-9]{1,9}$/, t = (t) => {
+	if (!e.test(t)) throw Error(`plan id prefix "${t}" is not 2 to 10 capital letters or digits, starting with a letter`);
+	return {
+		prefix: t,
+		plan: RegExp(`^${t}-PLAN-[0-9]{2}$`),
+		workItem: RegExp(`^${t}-[0-9]{2}-[0-9]{3}$`),
+		acceptance: RegExp(`^${t}-[0-9]{2}-[0-9]{3}-A[0-9]{2}$`),
+		requirement: RegExp(`^${t}-[0-9]{2}-[0-9]{3}-E[0-9]{2}$`),
+		source: RegExp(`^SRC-${t}-[0-9]{2}-[0-9]{3}-[0-9]{3}$`),
+		evidence: RegExp(`^EVD-${t}-[0-9]{2}-[0-9]{3}-[0-9]{3,}$`),
+		finding: RegExp(`^FND-${t}-[0-9]{2}-[0-9]{3}-[0-9]{3}$`),
+		adr: RegExp(`^ADR-${t}-[0-9]{3}$`),
+		closureRun: RegExp(`^CLR-${t}-[0-9]{2}-[0-9]{3}$`),
+		certificate: RegExp(`^CRT-${t}-[0-9]{2}-[0-9]{3}$`)
+	};
+}, n = (e) => {
+	let t = /-(?:PLAN-)?([0-9]{2})(?:-|$)/.exec(e);
+	return t === null ? null : t[1];
+}, r = (e, t) => {
+	let n = RegExp(`(?:^|-)(${e.prefix}-[0-9]{2}-[0-9]{3})(?:-|$)`).exec(t);
+	return n === null ? null : n[1];
+};
+//#endregion
+export { t as idGrammar, r as ownerItemOf, n as planNumberOf };

package/dist/impact.js

@@ -0,0 +1,65 @@
+//#region src/impact.ts
+var e = [
+	".",
+	":",
+	"/",
+	"-"
+], t = (t, n) => t === n || e.some((e) => n.startsWith(t + e) || t.startsWith(n + e)), n = (e, n) => {
+	let r = /* @__PURE__ */ new Map(), i = (e, t) => {
+		let n = r.get(e) ?? /* @__PURE__ */ new Set();
+		n.add(t), r.set(e, n);
+	};
+	for (let { item: r } of e.items.values()) for (let e of n.tags) for (let n of r.impactTags) t(e, n) && i(r.id, `tag ${n}`);
+	let a = [], o = new Map(e.instances.map(({ file: e, instance: t }) => [e, t])), s = /* @__PURE__ */ new Map();
+	for (let { item: t } of e.items.values()) for (let e of t.sourceRefs) {
+		let n = s.get(e.uri);
+		n === void 0 && (n = /* @__PURE__ */ new Set(), s.set(e.uri, n)), n.add(t.id);
+	}
+	for (let e of [...new Set(n.files)].sort()) {
+		let t = !1, n = o.get(e);
+		if (n !== void 0) {
+			t = !0;
+			for (let t of n.workItems) i(t.id, `its plan file ${e} changed`);
+		}
+		for (let n of s.get(e) ?? []) t = !0, i(n, `its source ${e} changed`);
+		t || a.push(e);
+	}
+	let c = /* @__PURE__ */ new Map();
+	for (let { item: t } of e.items.values()) for (let e of t.dependsOn) {
+		let n = c.get(e);
+		n === void 0 && (n = [], c.set(e, n)), n.push(t.id);
+	}
+	for (let e of c.values()) e.sort();
+	let l = /* @__PURE__ */ new Map(), u = [...r.keys()].sort().map((e) => [e]), d = new Set(r.keys());
+	for (let e = 0; e < u.length; e++) {
+		let t = u[e];
+		for (let e of c.get(t.at(-1)) ?? []) {
+			if (d.has(e)) continue;
+			d.add(e);
+			let n = [...t, e];
+			l.set(e, n), u.push(n);
+		}
+	}
+	let f = [...d], p = [...new Set(f.map((t) => e.items.get(t).item.ownerPlan))].sort(), m = p.flatMap((t) => {
+		let n = e.closure.get(t);
+		return n?.state === "certified" ? [{
+			plan: t,
+			certificate: n.certificate.id
+		}] : [];
+	});
+	return {
+		direct: [...r.entries()].map(([e, t]) => ({
+			workItem: e,
+			because: [...t].sort()
+		})).sort((e, t) => e.workItem < t.workItem ? -1 : 1),
+		transitive: [...l.entries()].map(([e, t]) => ({
+			workItem: e,
+			path: t
+		})).sort((e, t) => e.workItem < t.workItem ? -1 : 1),
+		plans: p,
+		certificates: m,
+		unknown: a
+	};
+};
+//#endregion
+export { n as impactOf };