Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

feat(sdk): persist security finding publication associations (#452)

Kyle Browndee278ae9993
diff --git a/sdk/typescript/_bundled_plugin/scripts/workbench_cli.py b/sdk/typescript/_bundled_plugin/scripts/workbench_cli.py
index 56f8997c7..77e9d56ac 100644
--- a/sdk/typescript/_bundled_plugin/scripts/workbench_cli.py
+++ b/sdk/typescript/_bundled_plugin/scripts/workbench_cli.py
@@ -304,6 +304,10 @@ def parse_args(description: str) -> argparse.Namespace:
export_findings.add_argument("--scan-id", required=True)
export_findings.add_argument("--format", choices=EXPORT_FORMATS, required=True)
+ for command in ("prepare-linear-publication", "record-linear-publications"):
+ publication = subparsers.add_parser(command)
+ publication.add_argument("--input-file", required=True)
+
subparsers.add_parser("database-info")
return parser.parse_args()
diff --git a/sdk/typescript/_bundled_plugin/scripts/workbench_db.py b/sdk/typescript/_bundled_plugin/scripts/workbench_db.py
index c5cb73c34..5584d3a13 100644
--- a/sdk/typescript/_bundled_plugin/scripts/workbench_db.py
+++ b/sdk/typescript/_bundled_plugin/scripts/workbench_db.py
@@ -2405,6 +2405,258 @@ def set_finding_remediation(
return scan_context(connection, occurrence["scan_id"])
+def linear_publication_input(
+ args: argparse.Namespace, *, recording: bool
+) -> tuple[dict[str, Any], dict[str, str], list[dict[str, str]]]:
+ payload = read_json_object(Path(args.input_file))
+ required = {"scanId", "scanDirectory", "destination", "findings"}
+ if recording:
+ required.add("publications")
+ if set(payload) != required:
+ raise SystemExit("Linear publication input contains unexpected or missing fields.")
+
+ scan_id = payload["scanId"]
+ scan_directory = payload["scanDirectory"]
+ destination = payload["destination"]
+ findings = payload["findings"]
+ if not isinstance(scan_id, str) or not isinstance(scan_directory, str):
+ raise SystemExit("Linear publication input must identify the exact completed scan.")
+ if (
+ not isinstance(destination, dict)
+ or not {"type", "teamId"}.issubset(destination)
+ or not set(destination).issubset({"type", "teamId", "projectId"})
+ or destination.get("type") != "linear"
+ or not isinstance(destination.get("teamId"), str)
+ or not destination["teamId"].strip()
+ or (
+ "projectId" in destination
+ and (
+ not isinstance(destination["projectId"], str)
+ or not destination["projectId"].strip()
+ )
+ )
+ ):
+ raise SystemExit("Linear publication input must identify the exact team and optional project.")
+ if not isinstance(findings, list):
+ raise SystemExit("Linear publication input must include the planned scan findings.")
+
+ seen_finding_ids: set[str] = set()
+ seen_occurrence_ids: set[str] = set()
+ for finding in findings:
+ if (
+ not isinstance(finding, dict)
+ or set(finding) != {"findingId", "occurrenceId"}
+ or not isinstance(finding.get("findingId"), str)
+ or not finding["findingId"].strip()
+ or not isinstance(finding.get("occurrenceId"), str)
+ or not finding["occurrenceId"].strip()
+ ):
+ raise SystemExit("Linear publication input contains an invalid finding identity.")
+ if (
+ finding["findingId"] in seen_finding_ids
+ or finding["occurrenceId"] in seen_occurrence_ids
+ ):
+ raise SystemExit("Linear publication input repeats a finding or occurrence.")
+ seen_finding_ids.add(finding["findingId"])
+ seen_occurrence_ids.add(finding["occurrenceId"])
+
+ return payload, destination, findings
+
+
+def verify_linear_publication_scan(
+ connection: sqlite3.Connection,
+ payload: dict[str, Any],
+ findings: list[dict[str, str]],
+) -> sqlite3.Row:
+ try:
+ scan = require_scan(connection, payload["scanId"])
+ except SystemExit as exc:
+ raise SystemExit(
+ "The completed scan is not present in the local Codex Security scan-history database. "
+ "Use the state directory where the scan was completed."
+ ) from exc
+ if scan["id"] != payload["scanId"]:
+ raise SystemExit("Linear publication must use the exact completed scan identifier.")
+ if scan["status"] != "complete":
+ raise SystemExit("Only completed scans can publish findings to Linear.")
+
+ requested_directory = require_canonical_scan_directory(Path(payload["scanDirectory"]))
+ recorded_directory = require_canonical_scan_directory(Path(scan["scan_dir"]))
+ if os.path.normcase(requested_directory) != os.path.normcase(recorded_directory):
+ raise SystemExit(
+ "The selected scan directory does not match its local Codex Security scan history."
+ )
+
+ stored_findings = {
+ row["id"]: row["finding_id"]
+ for row in connection.execute(
+ "SELECT id, finding_id FROM finding_occurrences WHERE scan_id = ?",
+ (scan["id"],),
+ )
+ }
+ for finding in findings:
+ if stored_findings.get(finding["occurrenceId"]) != finding["findingId"]:
+ raise SystemExit(
+ "A selected finding or occurrence does not belong to the completed scan "
+ "in local Codex Security scan history."
+ )
+ if len(stored_findings) != len(findings):
+ raise SystemExit(
+ "The completed scan findings do not exactly match local Codex Security scan history."
+ )
+ return scan
+
+
+def prepare_linear_publication(
+ connection: sqlite3.Connection, args: argparse.Namespace
+) -> dict[str, Any]:
+ payload, destination, findings = linear_publication_input(args, recording=False)
+ connection.execute("BEGIN IMMEDIATE")
+ try:
+ scan = verify_linear_publication_scan(connection, payload, findings)
+ result = {
+ "scanId": scan["id"],
+ "destination": destination,
+ "findingCount": len(findings),
+ }
+ connection.commit()
+ except BaseException:
+ connection.rollback()
+ raise
+ return result
+
+
+def record_linear_publications(
+ connection: sqlite3.Connection, args: argparse.Namespace
+) -> dict[str, Any]:
+ payload, destination, findings = linear_publication_input(args, recording=True)
+ publications = payload["publications"]
+ if not isinstance(publications, list):
+ raise SystemExit("Linear publication results must be an array.")
+ planned = {finding["findingId"]: finding["occurrenceId"] for finding in findings}
+ current: dict[str, dict[str, str]] = {}
+ external_ids: set[str] = set()
+ for publication in publications:
+ if (
+ not isinstance(publication, dict)
+ or not {"findingId", "occurrenceId", "issueIdentifier"}.issubset(publication)
+ or not set(publication).issubset(
+ {"findingId", "occurrenceId", "issueIdentifier", "url"}
+ )
+ or not isinstance(publication.get("findingId"), str)
+ or not isinstance(publication.get("occurrenceId"), str)
+ or not isinstance(publication.get("issueIdentifier"), str)
+ or not publication["issueIdentifier"].strip()
+ or (
+ "url" in publication
+ and (
+ not isinstance(publication["url"], str)
+ or not publication["url"].strip()
+ )
+ )
+ ):
+ raise SystemExit("Linear publication results contain an invalid issue association.")
+ finding_id = publication["findingId"]
+ issue_identifier = publication["issueIdentifier"]
+ if planned.get(finding_id) != publication["occurrenceId"]:
+ raise SystemExit(
+ "A created Linear issue does not match its planned finding and occurrence."
+ )
+ if finding_id in current or issue_identifier in external_ids:
+ raise SystemExit("Linear publication results repeat a finding or issue identifier.")
+ current[finding_id] = publication
+ external_ids.add(issue_identifier)
+
+ connection.execute("BEGIN IMMEDIATE")
+ try:
+ scan = verify_linear_publication_scan(connection, payload, findings)
+ timestamp = now()
+ for publication in publications:
+ conflicting = connection.execute(
+ """
+ SELECT occurrence_id, external_url
+ FROM finding_publications
+ WHERE destination_type = ? AND team_id = ? AND project_id IS ?
+ AND external_id = ?
+ """,
+ (
+ destination["type"],
+ destination["teamId"],
+ destination.get("projectId"),
+ publication["issueIdentifier"],
+ ),
+ ).fetchone()
+ if conflicting is not None and conflicting["occurrence_id"] != publication[
+ "occurrenceId"
+ ]:
+ raise SystemExit("This Linear issue is already associated with a different finding.")
+ if (
+ conflicting is not None
+ and "url" in publication
+ and conflicting["external_url"] != publication["url"]
+ ):
+ raise SystemExit("This Linear issue is already associated with a different URL.")
+
+ connection.execute(
+ """
+ INSERT INTO finding_publications (
+ scan_id, finding_id, occurrence_id, destination_type,
+ team_id, project_id, external_id, external_url, created_at
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+ ON CONFLICT DO NOTHING
+ """,
+ (
+ scan["id"],
+ publication["findingId"],
+ publication["occurrenceId"],
+ destination["type"],
+ destination["teamId"],
+ destination.get("projectId"),
+ publication["issueIdentifier"],
+ publication.get("url"),
+ timestamp,
+ ),
+ )
+
+ created = []
+ for finding in findings:
+ publication = current.get(finding["findingId"])
+ if publication is None:
+ continue
+ row = connection.execute(
+ """
+ SELECT finding_id, occurrence_id, external_id, external_url
+ FROM finding_publications
+ WHERE scan_id = ? AND occurrence_id = ? AND destination_type = ?
+ AND team_id = ? AND project_id IS ? AND external_id = ?
+ """,
+ (
+ scan["id"],
+ publication["occurrenceId"],
+ destination["type"],
+ destination["teamId"],
+ destination.get("projectId"),
+ publication["issueIdentifier"],
+ ),
+ ).fetchone()
+ if row is None:
+ raise SystemExit("A created Linear issue could not be read from scan history.")
+ created.append(
+ {
+ "findingId": row["finding_id"],
+ "occurrenceId": row["occurrence_id"],
+ "issueIdentifier": row["external_id"],
+ **({"url": row["external_url"]} if row["external_url"] is not None else {}),
+ }
+ )
+ result = {"scanId": scan["id"], "destination": destination, "created": created}
+ connection.commit()
+ except BaseException:
+ connection.rollback()
+ raise
+ return result
+
+
def export_findings(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
scan = require_scan(connection, args.scan_id)
if scan["status"] != "complete":
@@ -3730,6 +3982,10 @@ def main() -> None:
)
elif args.command == "set-finding-remediation":
result = set_finding_remediation(connection, args)
+ elif args.command == "prepare-linear-publication":
+ result = prepare_linear_publication(connection, args)
+ elif args.command == "record-linear-publications":
+ result = record_linear_publications(connection, args)
elif args.command == "export-findings":
result = export_findings(connection, args)
elif args.command == "database-info":
diff --git a/sdk/typescript/_bundled_plugin/scripts/workbench_schema.py b/sdk/typescript/_bundled_plugin/scripts/workbench_schema.py
index 93b8f297e..7fb414ae7 100644
--- a/sdk/typescript/_bundled_plugin/scripts/workbench_schema.py
+++ b/sdk/typescript/_bundled_plugin/scripts/workbench_schema.py
@@ -643,6 +643,46 @@ MIGRATIONS = (
ADD COLUMN max_time_hours REAL NOT NULL DEFAULT 96;
""",
),
+ (
+ 29,
+ "persist finding publication associations",
+ """
+ CREATE TABLE finding_publications (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ scan_id TEXT NOT NULL REFERENCES scans(id) ON DELETE CASCADE,
+ finding_id TEXT NOT NULL REFERENCES findings(id),
+ occurrence_id TEXT NOT NULL
+ REFERENCES finding_occurrences(id) ON DELETE CASCADE,
+ destination_type TEXT NOT NULL,
+ team_id TEXT,
+ project_id TEXT,
+ external_id TEXT NOT NULL,
+ external_url TEXT,
+ created_at TEXT NOT NULL,
+ UNIQUE (occurrence_id, destination_type, team_id, project_id, external_id),
+ UNIQUE (destination_type, team_id, project_id, external_id)
+ );
+
+ CREATE INDEX finding_publications_by_scan
+ ON finding_publications(scan_id, occurrence_id, id);
+
+ CREATE INDEX finding_publications_by_finding
+ ON finding_publications(finding_id, id);
+ """,
+ ),
+ (
+ 30,
+ "preserve team-only finding publication associations",
+ """
+ CREATE UNIQUE INDEX finding_publications_team_only_occurrence
+ ON finding_publications(occurrence_id, destination_type, team_id, external_id)
+ WHERE project_id IS NULL;
+
+ CREATE UNIQUE INDEX finding_publications_team_only_external_issue
+ ON finding_publications(destination_type, team_id, external_id)
+ WHERE project_id IS NULL;
+ """,
+ ),
)
diff --git a/sdk/typescript/scripts/check-package.mjs b/sdk/typescript/scripts/check-package.mjs
index 55ca44289..1d5f0ffd4 100644
--- a/sdk/typescript/scripts/check-package.mjs
+++ b/sdk/typescript/scripts/check-package.mjs
@@ -174,6 +174,7 @@ const distFiles = new Set(
"multiscan",
"publication",
"publication-events",
+ "publication-store",
"publish",
"result",
"runtime",
diff --git a/sdk/typescript/src/publication-store.ts b/sdk/typescript/src/publication-store.ts
new file mode 100644
index 000000000..866f5e06a
--- /dev/null
+++ b/sdk/typescript/src/publication-store.ts
@@ -0,0 +1,157 @@
+import { mkdtemp, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CodexSecurityError } from "./errors.js";
+import type { PreparedScanPublication } from "./publication.js";
+import type { PublishedScanIssue } from "./publish.js";
+import {
+ bundledPluginRoot,
+ codexSecurityStateDirectory,
+ resolvePluginPython,
+ runWorkbench,
+} from "./runtime.js";
+
+export async function preparePublicationStore(
+ publication: PreparedScanPublication,
+ environment: NodeJS.ProcessEnv,
+): Promise<void> {
+ const result = await runPublicationWorkbench(
+ "prepare-linear-publication",
+ publication,
+ environment,
+ );
+ if (
+ result["scanId"] !== publication.scanId ||
+ result["findingCount"] !== publication.issues.length
+ ) {
+ throw new CodexSecurityError(
+ "The workbench could not verify every finding selected for publication.",
+ );
+ }
+}
+
+export async function recordPublishedIssues(
+ publication: PreparedScanPublication,
+ issues: readonly PublishedScanIssue[],
+ environment: NodeJS.ProcessEnv,
+): Promise<PublishedScanIssue[]> {
+ const result = await runPublicationWorkbench(
+ "record-linear-publications",
+ publication,
+ environment,
+ issues,
+ );
+ const created = result["created"];
+ const destination = result["destination"];
+ if (
+ result["scanId"] !== publication.scanId ||
+ !isRecord(destination) ||
+ destination["type"] !== publication.destination.type ||
+ destination["teamId"] !== publication.destination.teamId ||
+ destination["projectId"] !== publication.destination.projectId ||
+ !Array.isArray(created) ||
+ created.length !== issues.length
+ ) {
+ throw invalidPublicationRecords();
+ }
+
+ const expected = new Map(issues.map((issue) => [issue.findingId, issue]));
+ const ordered = publication.issues.flatMap((issue) => {
+ const record = expected.get(issue.findingId);
+ return record === undefined ? [] : [record];
+ });
+ if (expected.size !== issues.length || ordered.length !== issues.length) {
+ throw invalidPublicationRecords();
+ }
+
+ return created.map((value, index) => {
+ const expectedIssue = ordered[index];
+ if (
+ !isRecord(value) ||
+ expectedIssue === undefined ||
+ value["findingId"] !== expectedIssue.findingId ||
+ value["occurrenceId"] !== expectedIssue.occurrenceId ||
+ value["issueIdentifier"] !== expectedIssue.issueIdentifier ||
+ (value["url"] !== undefined && typeof value["url"] !== "string") ||
+ (expectedIssue.url !== undefined && value["url"] !== expectedIssue.url)
+ ) {
+ throw invalidPublicationRecords();
+ }
+
+ return {
+ findingId: value["findingId"] as string,
+ occurrenceId: value["occurrenceId"] as string,
+ issueIdentifier: value["issueIdentifier"] as string,
+ ...(typeof value["url"] === "string" ? { url: value["url"] } : {}),
+ };
+ });
+}
+
+async function runPublicationWorkbench(
+ command: "prepare-linear-publication" | "record-linear-publications",
+ publication: PreparedScanPublication,
+ environment: NodeJS.ProcessEnv,
+ issues?: readonly PublishedScanIssue[],
+): Promise<Record<string, unknown>> {
+ const stateDirectory = codexSecurityStateDirectory(environment);
+ const database = join(stateDirectory, "workbench.sqlite3");
+ try {
+ if (!(await stat(database)).isFile()) throw new Error("not a regular file");
+ } catch (error) {
+ throw new CodexSecurityError(
+ "Cannot publish findings because the local Codex Security scan-history database does not exist. Use the state directory where this scan was completed.",
+ { cause: error },
+ );
+ }
+ const [python, pluginRoot] = await Promise.all([
+ resolvePluginPython({
+ environment,
+ protectedRoot: publication.scanDirectory,
+ }),
+ bundledPluginRoot(),
+ ]);
+ const findings = publication.issues.map(({ findingId, occurrenceId }) => ({
+ findingId,
+ occurrenceId,
+ }));
+ const directory = await mkdtemp(join(stateDirectory, "publication-"));
+ try {
+ const input = join(directory, "publication.json");
+ await writeFile(
+ input,
+ JSON.stringify({
+ scanId: publication.scanId,
+ scanDirectory: publication.scanDirectory,
+ destination: publication.destination,
+ findings,
+ ...(issues === undefined ? {} : { publications: issues }),
+ }),
+ { encoding: "utf8", flag: "wx", mode: 0o600 },
+ );
+ return await runWorkbench(
+ {
+ python,
+ pluginRoot,
+ environment,
+ failureMessage:
+ command === "prepare-linear-publication"
+ ? "Cannot publish findings without their existing local Codex Security scan history"
+ : "Could not persist created Linear issues in the local Codex Security scan history",
+ },
+ [command, "--input-file", input],
+ );
+ } finally {
+ await rm(directory, { recursive: true, force: true }).catch(
+ () => undefined,
+ );
+ }
+}
+
+function invalidPublicationRecords(): CodexSecurityError {
+ return new CodexSecurityError(
+ "The workbench returned invalid persisted Linear publication records.",
+ );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
diff --git a/sdk/typescript/tests-ts/publication-store.test.ts b/sdk/typescript/tests-ts/publication-store.test.ts
new file mode 100644
index 000000000..6fb9762ca
--- /dev/null
+++ b/sdk/typescript/tests-ts/publication-store.test.ts
@@ -0,0 +1,569 @@
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+ preparePublicationStore,
+ recordPublishedIssues,
+} from "../src/publication-store.js";
+import type { PreparedScanPublication } from "../src/publication.js";
+import type { PublishedScanIssue } from "../src/publish.js";
+import { runWorkbench } from "../src/runtime.js";
+import { PLUGIN_ROOT } from "./plugin-root.js";
+
+const SCAN_ID = "22222222-2222-4222-8222-222222222222";
+const OTHER_SCAN_ID = "33333333-3333-4333-8333-333333333333";
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+ await Promise.all(
+ temporaryDirectories
+ .splice(0)
+ .map((directory) => rm(directory, { recursive: true, force: true })),
+ );
+});
+
+interface PublicationFixture {
+ environment: NodeJS.ProcessEnv;
+ publication: PreparedScanPublication;
+ python: string;
+ stateDirectory: string;
+}
+
+async function publicationFixture(
+ options: {
+ count?: number;
+ createDatabase?: boolean;
+ seedScan?: boolean;
+ } = {},
+): Promise<PublicationFixture> {
+ const root = await realpath(
+ await mkdtemp(join(tmpdir(), "codex-security-publication-store-")),
+ );
+ temporaryDirectories.push(root);
+ const scanDirectory = join(root, "completed-scan");
+ await mkdir(scanDirectory, { mode: 0o700 });
+ const stateDirectory = join(root, "state");
+ const python = Bun.which("python3") ?? Bun.which("python") ?? Bun.which("py");
+ if (python === null) {
+ throw new Error(
+ "Publication workbench tests require a Python interpreter.",
+ );
+ }
+ const environment = {
+ ...process.env,
+ CODEX_SECURITY_STATE_DIR: stateDirectory,
+ PYTHON: python,
+ };
+ const publication: PreparedScanPublication = {
+ scanId: SCAN_ID,
+ uploadId: SCAN_ID,
+ scanDirectory,
+ destination: {
+ type: "linear",
+ teamId: "team-example",
+ projectId: "project-example",
+ },
+ issues: Array.from({ length: options.count ?? 2 }, (_, index) => ({
+ findingId: `finding-${index + 1}`,
+ occurrenceId: `occurrence-${index + 1}`,
+ title: `[Codex Security][HIGH] Example finding ${index + 1}`,
+ description: `Example finding ${index + 1}`,
+ priority: 2,
+ })),
+ };
+ const fixture = { environment, publication, python, stateDirectory };
+ if (options.createDatabase !== false) {
+ await runWorkbench({ python, pluginRoot: PLUGIN_ROOT, environment }, [
+ "database-info",
+ ]);
+ if (options.seedScan !== false) seedPublicationScan(fixture, publication);
+ }
+ return fixture;
+}
+
+function seedPublicationScan(
+ fixture: PublicationFixture,
+ publication: PreparedScanPublication,
+): void {
+ const workspaceId = randomUUID();
+ const seed = spawnSync(
+ fixture.python,
+ [
+ "-I",
+ "-B",
+ "-c",
+ [
+ "import json, sqlite3, sys",
+ "database, workspace_id, publication = sys.argv[1], sys.argv[2], json.loads(sys.argv[3])",
+ "connection = sqlite3.connect(database)",
+ "connection.execute('PRAGMA foreign_keys = ON')",
+ "timestamp = '2026-08-01T00:00:00Z'",
+ "connection.execute('INSERT INTO workspaces (id, created_at, updated_at) VALUES (?, ?, ?)', (workspace_id, timestamp, timestamp))",
+ "connection.execute('INSERT INTO scans (id, workspace_id, target_path, target_revision, scope, mode, scan_dir, status, phase, started_at, completed_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)', (publication['scanId'], workspace_id, publication['scanDirectory'], 'example-revision', '.', 'standard', publication['scanDirectory'], 'complete', 'reporting', timestamp, timestamp, timestamp, timestamp))",
+ "for issue in publication['issues']:",
+ " connection.execute('INSERT INTO findings (id, fingerprint, rule_id, identity_anchor, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(id) DO NOTHING', (issue['findingId'], 'fingerprint-' + issue['findingId'], 'example-rule', issue['findingId'], timestamp, timestamp))",
+ " connection.execute('INSERT INTO finding_occurrences (id, finding_id, scan_id, title, summary, severity, confidence, remediation, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)', (issue['occurrenceId'], issue['findingId'], publication['scanId'], issue['title'], 'example summary', 'high', 'high', 'example remediation', timestamp))",
+ "connection.commit()",
+ "connection.close()",
+ ].join("\n"),
+ join(fixture.stateDirectory, "workbench.sqlite3"),
+ workspaceId,
+ JSON.stringify(publication),
+ ],
+ { encoding: "utf8" },
+ );
+ expect(seed.status, seed.stderr).toBe(0);
+}
+
+function databaseRows(
+ fixture: PublicationFixture,
+ query: string,
+ values: readonly unknown[] = [],
+): Record<string, unknown>[] {
+ const result = spawnSync(
+ fixture.python,
+ [
+ "-I",
+ "-B",
+ "-c",
+ [
+ "import json, sqlite3, sys",
+ "connection = sqlite3.connect(sys.argv[1])",
+ "connection.row_factory = sqlite3.Row",
+ "cursor = connection.execute(sys.argv[2], json.loads(sys.argv[3]))",
+ "rows = [dict(row) for row in cursor.fetchall()] if cursor.description else []",
+ "connection.commit()",
+ "connection.close()",
+ "print(json.dumps(rows))",
+ ].join("\n"),
+ join(fixture.stateDirectory, "workbench.sqlite3"),
+ query,
+ JSON.stringify(values),
+ ],
+ { encoding: "utf8" },
+ );
+ expect(result.status, result.stderr).toBe(0);
+ return JSON.parse(result.stdout) as Record<string, unknown>[];
+}
+
+function publishedIssue(
+ publication: PreparedScanPublication,
+ index: number,
+ identifier = `EXAMPLE-${index + 1}`,
+): PublishedScanIssue {
+ const issue = publication.issues[index]!;
+ return {
+ findingId: issue.findingId,
+ occurrenceId: issue.occurrenceId,
+ issueIdentifier: identifier,
+ url: `https://linear.app/example/issue/${identifier}`,
+ };
+}
+
+describe("persisted finding publication associations", () => {
+ test("upgrades existing scan history and verifies every completed finding before publication", async () => {
+ const fixture = await publicationFixture();
+ databaseRows(fixture, "DROP TABLE finding_publications");
+ databaseRows(fixture, "DELETE FROM schema_migrations WHERE version >= ?", [
+ 29,
+ ]);
+
+ await expect(
+ preparePublicationStore(fixture.publication, fixture.environment),
+ ).resolves.toBeUndefined();
+
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT version, name FROM schema_migrations WHERE version >= ? ORDER BY version",
+ [29],
+ ),
+ ).toEqual([
+ { version: 29, name: "persist finding publication associations" },
+ {
+ version: 30,
+ name: "preserve team-only finding publication associations",
+ },
+ ]);
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT COUNT(*) AS count FROM finding_publications",
+ ),
+ ).toEqual([{ count: 0 }]);
+ });
+
+ test("upgrades existing project-scoped associations without changing recorded issues", async () => {
+ const fixture = await publicationFixture({ count: 1 });
+ const original = publishedIssue(fixture.publication, 0, "EXAMPLE-401");
+ await recordPublishedIssues(
+ fixture.publication,
+ [original],
+ fixture.environment,
+ );
+
+ databaseRows(
+ fixture,
+ "DROP INDEX finding_publications_team_only_occurrence",
+ );
+ databaseRows(
+ fixture,
+ "DROP INDEX finding_publications_team_only_external_issue",
+ );
+ databaseRows(fixture, "DELETE FROM schema_migrations WHERE version = ?", [
+ 30,
+ ]);
+
+ await expect(
+ preparePublicationStore(fixture.publication, fixture.environment),
+ ).resolves.toBeUndefined();
+
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT version, name FROM schema_migrations WHERE version = ?",
+ [30],
+ ),
+ ).toEqual([
+ {
+ version: 30,
+ name: "preserve team-only finding publication associations",
+ },
+ ]);
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT project_id, external_id FROM finding_publications",
+ ),
+ ).toEqual([
+ {
+ project_id: "project-example",
+ external_id: original.issueIdentifier,
+ },
+ ]);
+ });
+
+ test("rejects a missing local scan-history database without creating one", async () => {
+ const fixture = await publicationFixture({ createDatabase: false });
+
+ await expect(
+ preparePublicationStore(fixture.publication, fixture.environment),
+ ).rejects.toThrow(/scan-history database does not exist/u);
+
+ expect(existsSync(fixture.stateDirectory)).toBe(false);
+ });
+
+ test("rejects a scan absent from existing local scan history", async () => {
+ const fixture = await publicationFixture({ seedScan: false });
+
+ await expect(
+ preparePublicationStore(fixture.publication, fixture.environment),
+ ).rejects.toThrow(/scan is not present in the local/u);
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT COUNT(*) AS count FROM finding_publications",
+ ),
+ ).toEqual([{ count: 0 }]);
+ });
+
+ test("rejects an incomplete scan before publication", async () => {
+ const fixture = await publicationFixture();
+ databaseRows(fixture, "UPDATE scans SET status = ? WHERE id = ?", [
+ "running",
+ SCAN_ID,
+ ]);
+
+ await expect(
+ preparePublicationStore(fixture.publication, fixture.environment),
+ ).rejects.toThrow(/Only completed scans/u);
+ });
+
+ test("rejects a selected directory that differs from its recorded scan", async () => {
+ const fixture = await publicationFixture();
+ const anotherDirectory = join(fixture.stateDirectory, "another-scan");
+ await mkdir(anotherDirectory, { mode: 0o700 });
+
+ await expect(
+ preparePublicationStore(
+ { ...fixture.publication, scanDirectory: anotherDirectory },
+ fixture.environment,
+ ),
+ ).rejects.toThrow(/directory does not match/u);
+ });
+
+ test("rejects missing, mismatched, or omitted scan findings before publication", async () => {
+ const fixture = await publicationFixture();
+
+ for (const issues of [
+ [
+ {
+ ...fixture.publication.issues[0]!,
+ occurrenceId: "occurrence-not-in-scan",
+ },
+ fixture.publication.issues[1]!,
+ ],
+ [
+ { ...fixture.publication.issues[0]!, findingId: "finding-not-in-scan" },
+ fixture.publication.issues[1]!,
+ ],
+ [fixture.publication.issues[0]!],
+ ]) {
+ await expect(
+ preparePublicationStore(
+ { ...fixture.publication, issues },
+ fixture.environment,
+ ),
+ ).rejects.toThrow(/finding|occurrence/u);
+ }
+ });
+
+ test("rejects a real finding occurrence that belongs to another scan", async () => {
+ const fixture = await publicationFixture({ count: 1 });
+ const anotherDirectory = join(fixture.stateDirectory, "another-scan");
+ await mkdir(anotherDirectory, { mode: 0o700 });
+ const otherScan: PreparedScanPublication = {
+ ...fixture.publication,
+ scanId: OTHER_SCAN_ID,
+ uploadId: OTHER_SCAN_ID,
+ scanDirectory: anotherDirectory,
+ issues: [
+ {
+ ...fixture.publication.issues[0]!,
+ findingId: "finding-other-scan",
+ occurrenceId: "occurrence-other-scan",
+ },
+ ],
+ };
+ seedPublicationScan(fixture, otherScan);
+
+ await expect(
+ preparePublicationStore(
+ { ...fixture.publication, issues: otherScan.issues },
+ fixture.environment,
+ ),
+ ).rejects.toThrow(/does not belong to the completed scan/u);
+ });
+
+ test("returns only database-backed current results in original finding order", async () => {
+ const fixture = await publicationFixture();
+ const first = publishedIssue(fixture.publication, 0, "EXAMPLE-101");
+ const second = publishedIssue(fixture.publication, 1, "EXAMPLE-102");
+
+ const created = await recordPublishedIssues(
+ fixture.publication,
+ [second, first],
+ fixture.environment,
+ );
+
+ expect(created).toEqual([first, second]);
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT scan_id, finding_id, occurrence_id, destination_type, team_id, project_id, external_id, external_url FROM finding_publications ORDER BY finding_id",
+ ),
+ ).toEqual([
+ {
+ scan_id: SCAN_ID,
+ finding_id: first.findingId,
+ occurrence_id: first.occurrenceId,
+ destination_type: "linear",
+ team_id: "team-example",
+ project_id: "project-example",
+ external_id: first.issueIdentifier,
+ external_url: first.url,
+ },
+ {
+ scan_id: SCAN_ID,
+ finding_id: second.findingId,
+ occurrence_id: second.occurrenceId,
+ destination_type: "linear",
+ team_id: "team-example",
+ project_id: "project-example",
+ external_id: second.issueIdentifier,
+ external_url: second.url,
+ },
+ ]);
+ });
+
+ test("records optional issue URLs without inventing one", async () => {
+ const fixture = await publicationFixture({ count: 1 });
+ const issue = publishedIssue(fixture.publication, 0);
+ delete issue.url;
+
+ await expect(
+ recordPublishedIssues(fixture.publication, [issue], fixture.environment),
+ ).resolves.toEqual([issue]);
+ expect(
+ databaseRows(fixture, "SELECT external_url FROM finding_publications"),
+ ).toEqual([{ external_url: null }]);
+ });
+
+ test("persists team-only issues with a null project and rejects conflicting associations", async () => {
+ const fixture = await publicationFixture();
+ const publication: PreparedScanPublication = {
+ ...fixture.publication,
+ destination: {
+ type: "linear",
+ teamId: fixture.publication.destination.teamId,
+ },
+ };
+ const first = publishedIssue(publication, 0, "EXAMPLE-411");
+ const second = publishedIssue(publication, 1, "EXAMPLE-412");
+
+ await expect(
+ preparePublicationStore(publication, fixture.environment),
+ ).resolves.toBeUndefined();
+ await expect(
+ recordPublishedIssues(publication, [first], fixture.environment),
+ ).resolves.toEqual([first]);
+ await expect(
+ recordPublishedIssues(publication, [first], fixture.environment),
+ ).resolves.toEqual([first]);
+
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT project_id, external_id FROM finding_publications",
+ ),
+ ).toEqual([{ project_id: null, external_id: first.issueIdentifier }]);
+
+ await expect(
+ recordPublishedIssues(
+ publication,
+ [{ ...second, issueIdentifier: first.issueIdentifier }],
+ fixture.environment,
+ ),
+ ).rejects.toThrow(/already associated with a different finding/u);
+ await expect(
+ recordPublishedIssues(
+ publication,
+ [{ ...first, url: "https://linear.app/example/issue/EXAMPLE-OTHER" }],
+ fixture.environment,
+ ),
+ ).rejects.toThrow(/already associated with a different URL/u);
+
+ await expect(
+ recordPublishedIssues(publication, [first, second], fixture.environment),
+ ).resolves.toEqual([first, second]);
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT project_id, external_id FROM finding_publications ORDER BY id",
+ ),
+ ).toEqual([
+ { project_id: null, external_id: first.issueIdentifier },
+ { project_id: null, external_id: second.issueIdentifier },
+ ]);
+ });
+
+ test("replays exact associations without suppressing distinct issues on republish", async () => {
+ const fixture = await publicationFixture();
+ const original = publishedIssue(fixture.publication, 0, "EXAMPLE-201");
+ const replacement = publishedIssue(fixture.publication, 0, "EXAMPLE-202");
+ const additional = publishedIssue(fixture.publication, 1, "EXAMPLE-203");
+
+ await expect(
+ recordPublishedIssues(
+ fixture.publication,
+ [original],
+ fixture.environment,
+ ),
+ ).resolves.toEqual([original]);
+ await expect(
+ recordPublishedIssues(
+ fixture.publication,
+ [additional, replacement],
+ fixture.environment,
+ ),
+ ).resolves.toEqual([replacement, additional]);
+ await expect(
+ recordPublishedIssues(
+ fixture.publication,
+ [additional, replacement],
+ fixture.environment,
+ ),
+ ).resolves.toEqual([replacement, additional]);
+
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT COUNT(*) AS count FROM finding_publications",
+ ),
+ ).toEqual([{ count: 3 }]);
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT external_id FROM finding_publications WHERE finding_id = ? ORDER BY id",
+ [original.findingId],
+ ),
+ ).toEqual([
+ { external_id: original.issueIdentifier },
+ { external_id: replacement.issueIdentifier },
+ ]);
+ });
+
+ test("rejects swapped occurrences, duplicate mappings, and malformed issue IDs", async () => {
+ const fixture = await publicationFixture();
+ const first = publishedIssue(fixture.publication, 0);
+ const second = publishedIssue(fixture.publication, 1);
+
+ for (const records of [
+ [{ ...first, occurrenceId: second.occurrenceId }],
+ [first, { ...first, issueIdentifier: "EXAMPLE-999" }],
+ [first, { ...second, issueIdentifier: first.issueIdentifier }],
+ [{ ...first, issueIdentifier: " " }],
+ ]) {
+ await expect(
+ recordPublishedIssues(
+ fixture.publication,
+ records,
+ fixture.environment,
+ ),
+ ).rejects.toThrow(/finding|occurrence|issue|association/u);
+ }
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT COUNT(*) AS count FROM finding_publications",
+ ),
+ ).toEqual([{ count: 0 }]);
+ });
+
+ test("rolls back the entire import when an issue belongs to another finding", async () => {
+ const fixture = await publicationFixture();
+ const existing = publishedIssue(fixture.publication, 0, "EXAMPLE-301");
+ await recordPublishedIssues(
+ fixture.publication,
+ [existing],
+ fixture.environment,
+ );
+
+ await expect(
+ recordPublishedIssues(
+ fixture.publication,
+ [
+ publishedIssue(fixture.publication, 0, "EXAMPLE-302"),
+ publishedIssue(fixture.publication, 1, existing.issueIdentifier),
+ ],
+ fixture.environment,
+ ),
+ ).rejects.toThrow(/already associated with a different finding/u);
+
+ expect(
+ databaseRows(
+ fixture,
+ "SELECT finding_id, external_id FROM finding_publications ORDER BY id",
+ ),
+ ).toEqual([
+ {
+ finding_id: existing.findingId,
+ external_id: existing.issueIdentifier,
+ },
+ ]);
+ });
+});