reverseport 0.0.0-stage → 1.0.0

package/dist/domain/referenceSourceRequireBindings.js

@@ -0,0 +1,137 @@
+import * as t from "@babel/types";
+import { analyzeParsedJavaScriptReferences } from "./javascript/javascriptSemanticAnalysis.js";
+import { semanticBindingId, semanticScopeId, } from "./javascript/javascriptSemanticState.js";
+import { traverseJavaScriptAst } from "./javascript/javascriptSemanticTraversal.js";
+/**
+ * Keep calls that resolve either to Node's CommonJS wrapper loader or to a
+ * direct ESM `createRequire(import.meta.url)` binding. The shared lexical
+ * analyzer supplies binding ownership; this boundary accounts for the two
+ * Node loader bindings without evaluating arbitrary values.
+ */
+export const unshadowedReferenceSourceRequireCalls = (file, path) => {
+    const references = new Map(analyzeParsedJavaScriptReferences(file).map((reference) => [
+        `${reference.location.start.line}:${reference.location.start.column}`,
+        reference,
+    ]));
+    const programRequireBinding = semanticBindingId(semanticScopeId("program", file.program), "require");
+    const allowsUnboundRequire = !isExplicitModuleSource(path);
+    const hasTopLevelVarRequire = allowsUnboundRequire && hasUninitializedTopLevelVarRequire(file.program);
+    const createRequireBinding = directCreateRequireBinding(file.program, references);
+    const requireLoaderWasWritten = [...references.values()].some((reference) => reference.name === "require" &&
+        reference.role === "write" &&
+        (reference.resolution === "unbound" ||
+            reference.bindingId === programRequireBinding));
+    const calls = new Set();
+    traverseJavaScriptAst(file.program, {
+        enter: (node, _parent, readAncestors) => {
+            if (!t.isCallExpression(node))
+                return;
+            const identifier = requireCalleeIdentifier(node.callee);
+            const start = identifier?.loc?.start;
+            if (start === undefined)
+                return;
+            if (readAncestors().some((ancestor) => t.isWithStatement(ancestor) && contains(ancestor.body, node)))
+                return;
+            const reference = references.get(`${start.line}:${start.column}`);
+            if ((allowsUnboundRequire &&
+                !requireLoaderWasWritten &&
+                reference?.resolution === "unbound") ||
+                (((hasTopLevelVarRequire && !requireLoaderWasWritten) ||
+                    createRequireBinding) &&
+                    reference?.resolution === "resolved" &&
+                    reference.bindingId === programRequireBinding))
+                calls.add(node);
+        },
+    });
+    return calls;
+};
+const contains = (container, node) => typeof container.start === "number" &&
+    typeof container.end === "number" &&
+    typeof node.start === "number" &&
+    typeof node.end === "number" &&
+    container.start <= node.start &&
+    node.end <= container.end;
+const isExplicitModuleSource = (path) => {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".mjs") || lower.endsWith(".mts"))
+        return true;
+    if (lower.endsWith(".cjs") || lower.endsWith(".cts"))
+        return false;
+    // Syntax alone cannot establish Node's runtime mode: `.js` depends on its
+    // package scope, and `.ts` may be compiled with a CommonJS module target.
+    // Keep unmarked paths runtime-unknown and preserve candidate require edges.
+    return false;
+};
+const hasUninitializedTopLevelVarRequire = (program) => {
+    let found = false;
+    let initialized = false;
+    traverseJavaScriptAst(program, {
+        enter: (node, _parent, readAncestors) => {
+            if (!t.isVariableDeclaration(node, { kind: "var" }))
+                return;
+            if (readAncestors().some((ancestor) => t.isFunction(ancestor) || t.isStaticBlock(ancestor)))
+                return;
+            for (const declaration of node.declarations) {
+                if (!Object.hasOwn(t.getBindingIdentifiers(declaration.id), "require"))
+                    continue;
+                found = true;
+                initialized ||= declaration.init !== null;
+            }
+        },
+    });
+    return found && !initialized;
+};
+const directCreateRequireBinding = (program, references) => {
+    const programScope = semanticScopeId("program", program);
+    const importedNames = new Set();
+    for (const declaration of program.body) {
+        if (!t.isImportDeclaration(declaration) ||
+            (declaration.source.value !== "node:module" &&
+                declaration.source.value !== "module"))
+            continue;
+        for (const specifier of declaration.specifiers) {
+            if (t.isImportSpecifier(specifier) &&
+                t.isIdentifier(specifier.imported, { name: "createRequire" }))
+                importedNames.add(specifier.local.name);
+        }
+    }
+    return program.body.some((statement) => t.isVariableDeclaration(statement, { kind: "const" }) &&
+        statement.declarations.some((declaration) => {
+            if (!t.isIdentifier(declaration.id, { name: "require" }) ||
+                !t.isCallExpression(declaration.init) ||
+                !t.isIdentifier(declaration.init.callee) ||
+                !importedNames.has(declaration.init.callee.name) ||
+                !isImportMetaUrl(declaration.init.arguments[0]))
+                return false;
+            const start = declaration.init.callee.loc?.start;
+            if (start === undefined)
+                return false;
+            const reference = references.get(`${start.line}:${start.column}`);
+            return (reference?.resolution === "resolved" &&
+                reference.bindingId ===
+                    semanticBindingId(programScope, declaration.init.callee.name));
+        }));
+};
+const isImportMetaUrl = (node) => t.isMemberExpression(node) &&
+    !node.computed &&
+    t.isIdentifier(node.property, { name: "url" }) &&
+    t.isMetaProperty(node.object) &&
+    t.isIdentifier(node.object.meta, { name: "import" }) &&
+    t.isIdentifier(node.object.property, { name: "meta" });
+const requireCalleeIdentifier = (callee) => {
+    if (t.isIdentifier(callee, { name: "require" }))
+        return callee;
+    if (!t.isMemberExpression(callee) ||
+        !t.isIdentifier(callee.object, { name: "require" }) ||
+        ((!t.isIdentifier(callee.property) || callee.computed) &&
+            !t.isStringLiteral(callee.property)))
+        return undefined;
+    const propertyName = t.isIdentifier(callee.property)
+        ? callee.property.name
+        : t.isStringLiteral(callee.property)
+            ? callee.property.value
+            : undefined;
+    return propertyName === "resolve" || propertyName === "main"
+        ? callee.object
+        : undefined;
+};

package/dist/domain/relationshipCoverage.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+const diagnostics = z.array(z.string().min(1)).min(1);
+const completeCoverage = z.strictObject({ status: z.literal("complete") });
+const partialCoverage = z.strictObject({
+    status: z.literal("partial"),
+    limitations: z.array(z.string().min(1)).min(1),
+});
+const unknownCoverage = z.strictObject({
+    status: z.literal("unknown"),
+    reason: z.string().min(1),
+});
+/** Explicit coverage state for a provider's observed caller/callee set. */
+export const relationshipCoverageSchema = z.union([
+    completeCoverage,
+    completeCoverage.extend({ diagnostics }),
+    partialCoverage,
+    partialCoverage.extend({ diagnostics }),
+    unknownCoverage,
+    unknownCoverage.extend({ diagnostics }),
+]);

package/dist/domain/residualUnknown.js

@@ -0,0 +1,252 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { compareUnicodeCodePoints, compositeKey, } from "./unicodeCodePointOrder.js";
+import { prefixedDigestSchema } from "./../domain/digests.js";
+const evidenceIdSchema = prefixedDigestSchema("ev");
+const unknownIdSchema = prefixedDigestSchema("unk");
+const text = z.string().trim().min(1);
+const environmentRequirementSchema = z.object({
+    id: z.string().min(1).nullable(),
+    platform: z.string().min(1).nullable(),
+    architecture: z.string().min(1).nullable(),
+    isolation: z
+        .enum(["none", "process", "container", "virtual-machine"])
+        .nullable(),
+});
+const stableUnknownId = (question, domain, scopeDigest) => `unk_${createHash("sha256")
+    .update(canonicalJson({
+    domain: domain.trim(),
+    question: question.replace(/\s+/gu, " ").trim(),
+    scope_digest: scopeDigest,
+}))
+    .digest("hex")}`;
+const probeSchema = z.object({
+    operation: z.string().min(1),
+    rationale: text,
+});
+const relationshipSchema = z.object({
+    type: z.enum(["depends-on", "related-to", "contradicts"]),
+    unknown_id: unknownIdSchema,
+});
+const resolutionSchema = z.discriminatedUnion("disposition", [
+    z.object({
+        disposition: z.literal("verified"),
+        rationale: text,
+        evidence_ids: z.array(evidenceIdSchema).min(1),
+    }),
+    z.object({
+        disposition: z.enum(["withdrawn", "out-of-scope"]),
+        rationale: text,
+        evidence_ids: z.array(evidenceIdSchema),
+    }),
+]);
+/** Strict durable record for one unresolved or evidence-qualified question. */
+const residualUnknownObjectSchema = z.object({
+    unknown_id: unknownIdSchema,
+    revision: z.number().int().min(1),
+    previous_revision_digest: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    revision_digest: z.string().regex(/^[a-f0-9]{64}$/u),
+    scope_digest: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .nullable(),
+    question: text,
+    status: z.enum([
+        "open",
+        "investigating",
+        "blocked",
+        "contradicted",
+        "resolved",
+    ]),
+    severity: z.enum(["low", "medium", "high", "critical"]),
+    domain: text,
+    supporting_evidence_ids: z.array(evidenceIdSchema),
+    contradicting_evidence_ids: z.array(evidenceIdSchema),
+    required_authority: z
+        .enum([
+        "shipped-artifact",
+        "controlled-replay",
+        "historical-reference",
+        "external-service",
+        "analyst-inference",
+    ])
+        .nullable(),
+    required_confidence: z.enum(["observed", "derived", "inferred"]),
+    required_environment: environmentRequirementSchema.nullable(),
+    recommended_probes: z.array(probeSchema),
+    relationships: z.array(relationshipSchema),
+    resolution: resolutionSchema.nullable(),
+    mutation_evidence_ids: z.array(evidenceIdSchema).min(1),
+});
+const refineRevision = (value, context) => {
+    if (value.unknown_id !==
+        stableUnknownId(value.question, value.domain, value.scope_digest))
+        context.addIssue({
+            code: "custom",
+            message: "Residual unknown ID does not match its immutable identity",
+            path: ["unknown_id"],
+        });
+    if ((value.revision === 1) !== (value.previous_revision_digest === null))
+        context.addIssue({
+            code: "custom",
+            message: "Only the first revision has no predecessor",
+            path: ["previous_revision_digest"],
+        });
+    if ((value.status === "resolved") !== (value.resolution !== null))
+        context.addIssue({
+            code: "custom",
+            message: "Only resolved unknowns carry a resolution",
+            path: ["resolution"],
+        });
+    if (value.status === "contradicted" &&
+        value.contradicting_evidence_ids.length === 0)
+        context.addIssue({
+            code: "custom",
+            message: "Contradicted status requires contradicting evidence",
+            path: ["contradicting_evidence_ids"],
+        });
+    if (value.relationships.some((relationship) => relationship.unknown_id === value.unknown_id))
+        context.addIssue({
+            code: "custom",
+            message: "An unknown cannot relate to itself",
+            path: ["relationships"],
+        });
+    for (const ids of [
+        value.supporting_evidence_ids,
+        value.contradicting_evidence_ids,
+        value.mutation_evidence_ids,
+    ])
+        if (new Set(ids).size !== ids.length)
+            context.addIssue({
+                code: "custom",
+                message: "Evidence IDs must be unique",
+            });
+    const contradictingEvidence = new Set(value.contradicting_evidence_ids);
+    if (value.supporting_evidence_ids.some((id) => contradictingEvidence.has(id)))
+        context.addIssue({
+            code: "custom",
+            message: "Evidence cannot simultaneously support and contradict",
+        });
+    const relationships = value.relationships.map((relationship) => `${relationship.type}:${relationship.unknown_id}`);
+    if (new Set(relationships).size !== relationships.length)
+        context.addIssue({
+            code: "custom",
+            message: "Relationships must be unique",
+            path: ["relationships"],
+        });
+};
+export const residualUnknownSchema = residualUnknownObjectSchema.superRefine((value, context) => {
+    if (computeRevisionDigest(value) !== value.revision_digest)
+        context.addIssue({
+            code: "custom",
+            message: "Residual unknown revision digest does not match",
+            path: ["revision_digest"],
+        });
+    refineRevision(value, context);
+});
+const generatedRevisionSchema = residualUnknownObjectSchema
+    .omit({ revision_digest: true })
+    .superRefine(refineRevision);
+/** Input for deterministic creation of one residual unknown. */
+export const recordUnknownInputSchema = residualUnknownObjectSchema
+    .omit({
+    unknown_id: true,
+    revision: true,
+    previous_revision_digest: true,
+    revision_digest: true,
+    scope_digest: true,
+    status: true,
+    supporting_evidence_ids: true,
+    contradicting_evidence_ids: true,
+    resolution: true,
+    mutation_evidence_ids: true,
+})
+    .extend({
+    supporting_evidence_ids: z.array(evidenceIdSchema).default([]),
+    contradicting_evidence_ids: z.array(evidenceIdSchema).default([]),
+})
+    .strict();
+/** Explicit optimistic-concurrency update command for one unknown. */
+export const updateUnknownInputSchema = z.strictObject({
+    unknown_id: unknownIdSchema,
+    expected_revision: z.number().int().min(1),
+    status: residualUnknownObjectSchema.shape.status,
+    severity: residualUnknownObjectSchema.shape.severity,
+    supporting_evidence_ids: z.array(evidenceIdSchema),
+    contradicting_evidence_ids: z.array(evidenceIdSchema),
+    required_authority: residualUnknownObjectSchema.shape.required_authority,
+    required_confidence: residualUnknownObjectSchema.shape.required_confidence,
+    required_environment: environmentRequirementSchema.nullable(),
+    recommended_probes: z.array(probeSchema),
+    relationships: z.array(relationshipSchema),
+    resolution: resolutionSchema.nullable(),
+});
+/** Create stable identity from immutable question and domain fields. */
+export const createResidualUnknown = (input, mutationEvidenceId, scopeDigest) => {
+    const question = input.question.replace(/\s+/gu, " ").trim();
+    const domain = input.domain.trim();
+    const revision = {
+        unknown_id: stableUnknownId(question, domain, scopeDigest),
+        revision: 1,
+        previous_revision_digest: null,
+        scope_digest: scopeDigest,
+        question,
+        status: input.contradicting_evidence_ids.length > 0 ? "contradicted" : "open",
+        domain,
+        ...projectRevisionDetails(input),
+        resolution: null,
+        mutation_evidence_ids: [mutationEvidenceId],
+    };
+    return createRevision(revision);
+};
+/** Apply a complete, revision-guarded replacement while preserving identity. */
+export const updateResidualUnknown = (current, input, mutationEvidenceId) => {
+    const revision = {
+        unknown_id: current.unknown_id,
+        revision: current.revision + 1,
+        previous_revision_digest: current.revision_digest,
+        scope_digest: current.scope_digest,
+        question: current.question,
+        status: input.status,
+        domain: current.domain,
+        ...projectRevisionDetails(input),
+        resolution: input.resolution,
+        mutation_evidence_ids: sortedUnique([
+            ...current.mutation_evidence_ids,
+            mutationEvidenceId,
+        ]),
+    };
+    return createRevision(revision);
+};
+/** Validate and normalize owned revision fields before computing their digest. */
+const createRevision = (value) => {
+    const revision = generatedRevisionSchema.parse(value);
+    return { ...revision, revision_digest: computeRevisionDigest(revision) };
+};
+const projectRevisionDetails = (input) => ({
+    severity: input.severity,
+    supporting_evidence_ids: sortedUnique(input.supporting_evidence_ids),
+    contradicting_evidence_ids: sortedUnique(input.contradicting_evidence_ids),
+    required_authority: input.required_authority,
+    required_confidence: input.required_confidence,
+    required_environment: input.required_environment,
+    recommended_probes: [...input.recommended_probes],
+    relationships: sortedRelationships(input.relationships),
+});
+const computeRevisionDigest = (value) => {
+    const { revision_digest: _revisionDigest, ...semantic } = "revision_digest" in value ? value : { ...value, revision_digest: "" };
+    void _revisionDigest;
+    return createHash("sha256").update(canonicalJson(semantic)).digest("hex");
+};
+const canonicalJson = (value) => {
+    const serialized = canonicalize(value);
+    if (serialized === undefined)
+        throw new TypeError("Unknown identity failed");
+    return serialized;
+};
+const sortedUnique = (values) => [...new Set(values)].sort(compareUnicodeCodePoints);
+const sortedRelationships = (values) => [...values].sort((left, right) => compareUnicodeCodePoints(compositeKey([left.type, left.unknown_id]), compositeKey([right.type, right.unknown_id])));

package/dist/domain/result.js

@@ -0,0 +1,4 @@
+/** Construct a successful result. */
+export const ok = (value) => ({ ok: true, value });
+/** Construct a failed result. */
+export const err = (error) => ({ ok: false, error });

package/dist/domain/runtimeVersion.js

@@ -0,0 +1,15 @@
+import { satisfies } from "semver";
+/** Supported runtime range, kept in sync with the published package engines. */
+export const SUPPORTED_NODE_VERSION_RANGE = "^22.19.0 || ^24.11.0 || >=26.0.0";
+/** Human-readable form of {@link SUPPORTED_NODE_VERSION_RANGE} for remediation. */
+export const SUPPORTED_NODE_VERSION_PROSE = "Node.js 22.x (>=22.19), 24.x (>=24.11), or 26+";
+/** Return whether a Node.js version satisfies REA's tested runtime families. */
+export const supportsNodeVersion = (version) => satisfies(version, SUPPORTED_NODE_VERSION_RANGE);
+/** Identify the runtime from `process.versions`; only Bun reports `bun`. */
+export const javaScriptRuntime = (versions) => versions.bun === undefined
+    ? { id: "node", version: versions.node }
+    : {
+        id: "bun",
+        version: versions.bun,
+        nodeCompatibilityVersion: versions.node,
+    };

package/dist/domain/safeJson.js

@@ -0,0 +1,13 @@
+/** Parse JSON text, returning the failure reason instead of throwing. */
+export const safeParseJson = (value) => {
+    try {
+        return { ok: true, value: JSON.parse(value) };
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            error: cause instanceof Error ? cause.message : String(cause),
+            cause,
+        };
+    }
+};

package/dist/domain/sourceMapContents.js

@@ -0,0 +1,6 @@
+/** Validate optional source-map content against its source inventory. */
+export const hasValidSourceMapContents = (sourceCount, contents) => contents === undefined ||
+    contents === null ||
+    (Array.isArray(contents) &&
+        contents.length === sourceCount &&
+        contents.every((content) => content === null || typeof content === "string"));

package/dist/domain/sourceMapEnvelope.js

@@ -0,0 +1,44 @@
+/**
+ * Return the JSON parsing view of retained source-map text. ECMA-426 permits
+ * HTTP responses to start with `)]}'`; the first line is transport framing.
+ * Keep the original text for artifact identity and Evidence provenance.
+ * https://tc39.es/ecma426/#sec-fetchsourcemap
+ */
+export const sourceMapJsonText = (text) => {
+    const withoutBom = text.replace(/^\uFEFF/u, "");
+    if (!withoutBom.startsWith(")]}'"))
+        return withoutBom;
+    const newline = withoutBom.search(/[\r\n]/u);
+    return newline === -1 ? "" : withoutBom.slice(newline);
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Whether a parsed value has the version-3 map shape. */
+const isVersion3Map = (value) => isRecord(value) && value.version === 3;
+/**
+ * Collect leaf maps from an indexed source-map envelope, or undefined when
+ * the envelope is not a version-3 map. A map carrying neither `mappings`
+ * nor `sections` yields itself as the single leaf; callers decide whether
+ * that leaf is valid content.
+ */
+export const flattenSourceMapLeaves = (root) => {
+    if (!isVersion3Map(root))
+        return undefined;
+    const leaves = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const map = pending.pop();
+        if (!isVersion3Map(map))
+            return undefined;
+        if (Array.isArray(map.sections)) {
+            for (let index = map.sections.length - 1; index >= 0; index -= 1) {
+                const section = map.sections[index];
+                if (!isRecord(section) || !isRecord(section.map))
+                    return undefined;
+                pending.push(section.map);
+            }
+        }
+        else
+            leaves.push(map);
+    }
+    return leaves;
+};