pi-apexlang 0.2.1 → 0.2.2

package/README.md

@@ -103,6 +103,45 @@ repeat export produces one current snapshot instead of collision copies such
 as `application_1.apx` and `p00005_1.apx`. Because this replaces the complete
 local export, preserve or import any local-only work before refreshing it.
 
+## SQLcl and ORDS compatibility advisory
+
+Oracle documents minimum APEXlang prerequisites, but does not publish an exact
+ORDS-to-SQLcl patch certification matrix. The extension therefore keeps this
+mapping advisory and records whether a row is Oracle-confirmed or an extension
+diagnostic recommendation:
+
+| Server environment | SQLcl guidance | Basis |
+| --- | --- | --- |
+| ORDS before 26.1.1 or APEX before 26.1 | APEXlang is unsupported; upgrade the server components first. | Oracle-confirmed |
+| APEX 26.1.x with ORDS 26.1.1 through 26.1.x | Oracle minimum: SQLcl 26.1. Diagnostic baseline: `26.1.2.132.1334`. | Oracle minimum plus extension advisory |
+| APEX 26.1.x with ORDS 26.2.x | Oracle does not mandate SQLcl 26.2. On mass findings, compare with `26.1.2.132.1334`. | Extension advisory |
+| Other or newer APEX, MMD, or ORDS lines | Verify current Oracle release documentation and use compiler metadata supporting the app `mmdVersion`. | Verify current docs |
+
+The complete machine-readable table, source URLs, thresholds, and the direct
+diagnostic-build download are in
+[`extensions/apexlang/ords-sqlcl-compatibility.json`](extensions/apexlang/ords-sqlcl-compatibility.json).
+The exact build is a known diagnostic baseline, not a universal pin, and SQLcl
+26.2 is not categorically blocked.
+
+When a validation result contains at least 50 structured findings, the
+extension appends the table and recommends checking:
+
+- local `sql -version`;
+- the app's `.apex/apexlang.json` `mmdVersion`;
+- the server APEX release and ORDS version with its administrator.
+
+For local and compiler-truth text reports, the mass-error signal additionally
+requires at least five distinct `.apx` files, which avoids treating one noisy
+file as an environment-wide mismatch. An explicitly unsupported MMD version
+also produces the compatibility advice. The advice never changes validation
+status, relaxes an import gate, or claims that the application is valid.
+
+[ORDS 26.1.1 introduced APEXlang support](https://www.oracle.com/tools/ords/ords-relnotes-26.1.1.html),
+[APEX 26.1 requires ORDS 26.1.1 or later](https://docs.oracle.com/en/database/oracle/apex/26.1/htmrn/changed-behavior.html),
+and Oracle's [SQLcl prerequisites](https://docs.oracle.com/en/database/oracle/sql-developer-command-line/26.1/sqcug/prerequisites-apexlang.html)
+set the SQLcl minimum at 26.1. SQLcl
+[26.1.2 added full APEXlang support](https://www.oracle.com/tools/sqlcl/sqlcl-relnotes-26.1.2.html).
+
 All app paths must remain inside the active Pi workspace. The adapter rejects
 traversal, app-tree symlinks, and multiply linked files on mutating vocabulary
 fixes; verifies live workspace input against `deployments/default.json`; and
@@ -116,8 +155,9 @@ Offline routing, templates, generation, and most local checks need Node.js
 
 Oracle documents these requirements for live APEXlang work:
 
-- Oracle APEX with APEXlang support, using the latest available 26.1 build.
-- SQLcl 26.1.2 or newer.
+- Oracle APEX 26.1 with APEXlang support.
+- ORDS 26.1.1 or newer.
+- SQLcl 26.1 or newer, selected with the compatibility advisory above.
 - Java 17 or Java 21 for SQLcl.
 - A saved SQLcl connection name and its corresponding APEX workspace name.
 - A local APEX app or authoritative schema, model, API, or table metadata.

package/extensions/apexlang/compatibility.ts

@@ -0,0 +1,227 @@
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import compatibility from "./ords-sqlcl-compatibility.json" with { type: "json" };
+import type { ApexlangRunResult } from "../lib/apexlang-cli.mjs";
+
+type JsonRecord = Record<string, unknown>;
+
+export type ValidationCompatibilitySignal = {
+  findingCount?: number;
+  distinctFileCount?: number;
+  source: "structured-result" | "local-reports" | "compiler-truth-output" | "unsupported-mmd";
+};
+
+export const ORDS_SQLCL_COMPATIBILITY = compatibility;
+export const ORDS_SQLCL_COMPATIBILITY_TABLE = compatibility.rows;
+export const MASS_VALIDATION_FINDING_THRESHOLD = compatibility.massValidation.minimumFindings;
+export const MASS_VALIDATION_DISTINCT_FILE_THRESHOLD =
+  compatibility.massValidation.minimumDistinctFilesForAppWideReports;
+export const ORDS_SQLCL_COMPATIBILITY_GUIDELINE =
+  `When a validation action reports ${MASS_VALIDATION_FINDING_THRESHOLD}+ findings, recommend checking the server APEX/ORDS release, the app mmdVersion, and local \`sql -version\` against the extension's advisory compatibility table. For APEX 26.1, SQLcl 26.1 is Oracle's minimum and 26.1.2.132.1334 is the diagnostic baseline; do not hard-block other SQLcl versions or weaken validation/import gates.`;
+
+const VALIDATION_ACTIONS = new Set([
+  "local_validate",
+  "compiler_truth_audit",
+  "runtime_validate"
+]);
+const LOCAL_VALIDATION_REPORT_NAMES = [
+  "apexlang-dsl-report.json",
+  "apexlang-validations-report.json",
+  "apexlang-vocab-report.json"
+] as const;
+
+function asRecord(value: unknown): JsonRecord | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as JsonRecord
+    : undefined;
+}
+
+function parseJsonRecord(value: string): JsonRecord | undefined {
+  try {
+    return asRecord(JSON.parse(value));
+  } catch {
+    return undefined;
+  }
+}
+
+function safeCount(value: unknown): number | undefined {
+  return Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : undefined;
+}
+
+function maximumStructuredFindingCount(payload: JsonRecord): number | undefined {
+  const compatibilityFallback = asRecord(payload.compatibility_fallback);
+  const candidates = [
+    safeCount(payload.unresolved_count),
+    safeCount(payload.problem_count),
+    Array.isArray(payload.issues) ? payload.issues.length : undefined,
+    Array.isArray(payload.problems) ? payload.problems.length : undefined,
+    safeCount(compatibilityFallback?.original_unresolved_count)
+  ].filter((value): value is number => value !== undefined);
+  return candidates.length > 0 ? Math.max(...candidates) : undefined;
+}
+
+function diagnosticIdentity(issue: unknown, reportName: string, index: number): {
+  key: string;
+  file?: string;
+} {
+  if (typeof issue === "string") {
+    const raw = issue.trim();
+    const match = raw.match(/^\s*-?\s*(.+?\.apx):(\d+)(?::\d+)?:\s+[A-Z][A-Z0-9_]+\b/);
+    return { key: raw || `${reportName}:${index}`, ...(match?.[1] ? { file: match[1] } : {}) };
+  }
+
+  const record = asRecord(issue);
+  if (!record) return { key: `${reportName}:${index}:${String(issue)}` };
+  const file = typeof record.file === "string" ? record.file.trim() : "";
+  const raw = typeof record.raw === "string" ? record.raw.trim() : "";
+  const key = raw || [
+    file,
+    String(record.line ?? ""),
+    String(record.column ?? ""),
+    String(record.rule ?? record.code ?? ""),
+    String(record.message ?? "")
+  ].join(":");
+  return {
+    key: key || `${reportName}:${index}:${JSON.stringify(record)}`,
+    ...(file ? { file } : {})
+  };
+}
+
+async function readJsonReport(path: string): Promise<JsonRecord | undefined> {
+  try {
+    return parseJsonRecord(await readFile(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+export async function clearLocalValidationCompatibilityReports(outputRoot: string): Promise<void> {
+  await Promise.all(
+    LOCAL_VALIDATION_REPORT_NAMES.map((name) => rm(join(outputRoot, "logs", name), { force: true }))
+  );
+}
+
+async function detectLocalReportSignal(outputRoot: string): Promise<ValidationCompatibilitySignal | undefined> {
+  const reports = await Promise.all(
+    LOCAL_VALIDATION_REPORT_NAMES.map(async (name) => ({
+      name,
+      payload: await readJsonReport(join(outputRoot, "logs", name))
+    }))
+  );
+  const vocabularyReport = reports.find(({ name }) => name === "apexlang-vocab-report.json")?.payload;
+  if (vocabularyReport?.blocking_reason === "UNSUPPORTED_MMD_VERSION") {
+    return { source: "unsupported-mmd" };
+  }
+
+  const findingKeys = new Set<string>();
+  const files = new Set<string>();
+  for (const { name, payload } of reports) {
+    for (const collection of [payload?.issues, payload?.unresolved]) {
+      if (!Array.isArray(collection)) continue;
+      collection.forEach((issue, index) => {
+        const identity = diagnosticIdentity(issue, name, index);
+        findingKeys.add(identity.key);
+        if (identity.file) files.add(identity.file);
+      });
+    }
+  }
+  if (
+    findingKeys.size >= MASS_VALIDATION_FINDING_THRESHOLD &&
+    files.size >= MASS_VALIDATION_DISTINCT_FILE_THRESHOLD
+  ) {
+    return {
+      source: "local-reports",
+      findingCount: findingKeys.size,
+      distinctFileCount: files.size
+    };
+  }
+  return undefined;
+}
+
+function detectCompilerTruthOutputSignal(output: string): ValidationCompatibilitySignal | undefined {
+  const findings = new Set<string>();
+  const files = new Set<string>();
+  for (const line of output.split(/\r?\n/)) {
+    const match = line.match(/^\s*-\s+(.+?\.apx):(\d+)(?::\d+)?:\s+([A-Z][A-Z0-9_]+)\b\s*(.*)$/);
+    if (!match?.[1]) continue;
+    findings.add(`${match[1]}:${match[2]}:${match[3]}:${match[4] ?? ""}`);
+    files.add(match[1]);
+  }
+  if (
+    findings.size >= MASS_VALIDATION_FINDING_THRESHOLD &&
+    files.size >= MASS_VALIDATION_DISTINCT_FILE_THRESHOLD
+  ) {
+    return {
+      source: "compiler-truth-output",
+      findingCount: findings.size,
+      distinctFileCount: files.size
+    };
+  }
+  return undefined;
+}
+
+export async function detectValidationCompatibilitySignal(
+  result: ApexlangRunResult
+): Promise<ValidationCompatibilitySignal | undefined> {
+  if (!VALIDATION_ACTIONS.has(result.action)) return undefined;
+
+  const payload = parseJsonRecord(result.stdout);
+  if (payload) {
+    const findingCount = maximumStructuredFindingCount(payload);
+    if (findingCount !== undefined && findingCount >= MASS_VALIDATION_FINDING_THRESHOLD) {
+      return { source: "structured-result", findingCount };
+    }
+  }
+  if (result.action === "local_validate") {
+    return detectLocalReportSignal(result.outputRoot);
+  }
+  if (result.action === "compiler_truth_audit") {
+    return detectCompilerTruthOutputSignal([result.stdout, result.stderr].filter(Boolean).join("\n"));
+  }
+  return undefined;
+}
+
+function tableCell(value: string): string {
+  return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+export function renderOrdsSqlclCompatibilityTable(): string {
+  const rows = ORDS_SQLCL_COMPATIBILITY_TABLE.map((row) => {
+    const guidance = row.diagnosticSqlclBuild && row.diagnosticSqlclDownloadUrl
+      ? `${row.sqlclGuidance} [Download ${row.diagnosticSqlclBuild}](${row.diagnosticSqlclDownloadUrl})`
+      : row.sqlclGuidance;
+    return `| ${tableCell(row.environment)} | ${tableCell(guidance)} | ${tableCell(row.basis)} |`;
+  });
+  return [
+    "| Server environment | SQLcl guidance | Basis |",
+    "| --- | --- | --- |",
+    ...rows
+  ].join("\n");
+}
+
+export function formatValidationCompatibilityAdvisory(
+  signal: ValidationCompatibilitySignal
+): string {
+  const findingSummary = signal.findingCount === undefined
+    ? "The application declares an unsupported APEXlang compiler metadata version."
+    : `Large-scale validation output detected (${signal.findingCount} findings${
+        signal.distinctFileCount === undefined ? "" : ` across ${signal.distinctFileCount} files`
+      }).`;
+  return [
+    "### SQLcl/ORDS compatibility advisory",
+    "",
+    `${findingSummary} Before changing many application files, check local \`sql -version\`, the app's \`.apex/apexlang.json\` \`mmdVersion\`, and the server APEX and ORDS versions with its administrator. A version/metadata mismatch can create broad diagnostic noise.`,
+    "",
+    renderOrdsSqlclCompatibilityTable(),
+    "",
+    compatibility.caveat,
+    "This advice does not turn a failed validation into a pass and does not authorize import."
+  ].join("\n");
+}
+
+export async function buildValidationCompatibilityAdvisory(
+  result: ApexlangRunResult
+): Promise<string> {
+  const signal = await detectValidationCompatibilitySignal(result);
+  return signal ? formatValidationCompatibilityAdvisory(signal) : "";
+}

package/extensions/apexlang/index.ts

@@ -13,6 +13,18 @@ import {
   type ApexlangInput,
   type ApexlangRunResult
 } from "../lib/apexlang-cli.mjs";
+import {
+  MASS_VALIDATION_DISTINCT_FILE_THRESHOLD,
+  MASS_VALIDATION_FINDING_THRESHOLD,
+  ORDS_SQLCL_COMPATIBILITY,
+  ORDS_SQLCL_COMPATIBILITY_GUIDELINE,
+  ORDS_SQLCL_COMPATIBILITY_TABLE,
+  buildValidationCompatibilityAdvisory,
+  clearLocalValidationCompatibilityReports,
+  detectValidationCompatibilitySignal,
+  formatValidationCompatibilityAdvisory,
+  renderOrdsSqlclCompatibilityTable
+} from "./compatibility.ts";
 
 const MAX_TOOL_OUTPUT = 80_000;
 const COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
@@ -77,14 +89,20 @@ function createNewTargetProved(result: ApexlangRunResult): boolean {
     payload?.failure_class === "create_new_confirmation_required";
 }
 
-function processOutput(result: ApexlangRunResult): string {
+function processOutput(result: ApexlangRunResult, compatibilityAdvisory = ""): string {
   const streams = result.ok ? [result.stdout, result.stderr] : [result.stderr, result.stdout];
-  return trimOutput(streams.filter(Boolean).join("\n").trim(), result.outputRoot);
+  const output = trimOutput(streams.filter(Boolean).join("\n").trim(), result.outputRoot);
+  return [output, compatibilityAdvisory].filter(Boolean).join("\n\n");
 }
 
-function failureOutput(result: ApexlangRunResult, fallback: string): string {
-  const output = processOutput(result) || fallback;
-  return `${output}\n\nAPEXlang reports: ${result.outputRoot}`;
+function failureOutput(
+  result: ApexlangRunResult,
+  fallback: string,
+  compatibilityAdvisory = ""
+): string {
+  const streams = result.ok ? [result.stdout, result.stderr] : [result.stderr, result.stdout];
+  const output = trimOutput(streams.filter(Boolean).join("\n").trim(), result.outputRoot) || fallback;
+  return `${[output, compatibilityAdvisory].filter(Boolean).join("\n\n")}\n\nAPEXlang reports: ${result.outputRoot}`;
 }
 
 type ApexlangDependencies = {
@@ -113,6 +131,7 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
     "Load the apexlang skill before using the apexlang tool and follow its routing and Missing Inputs rules.",
     "Use apexlang workspace_probe before app-scoped APEXlang work.",
     EXPORT_OVERWRITE_GUIDELINE,
+    ORDS_SQLCL_COMPATIBILITY_GUIDELINE,
     "Use apexlang runtime_validate only after the user provides both db_connection_name and the matching APEX workspace_name; import requires the tool's separate post-check GUI choice."
   ],
   executionMode: "sequential",
@@ -194,11 +213,25 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
       ...(signal ? { signal } : {}),
       timeoutMs: COMMAND_TIMEOUT_MS
     };
+    if (input.action === "local_validate") {
+      await clearLocalValidationCompatibilityReports(outputRoot);
+    }
     const result = await dependencies.run(input, runOptions);
-    const output = processOutput(result);
+    const compatibilityAdvisory = await buildValidationCompatibilityAdvisory(result);
+    if (compatibilityAdvisory) {
+      onUpdate?.({
+        content: [{ type: "text", text: compatibilityAdvisory }],
+        details: { action: input.action, compatibilityAdvisory: true }
+      });
+    }
+    const output = processOutput(result, compatibilityAdvisory);
     if (!result.ok) {
       throw new Error(
-        failureOutput(result, `APEXlang ${input.action} failed with exit code ${result.code}.`)
+        failureOutput(
+          result,
+          `APEXlang ${input.action} failed with exit code ${result.code}.`,
+          compatibilityAdvisory
+        )
       );
     }
 
@@ -207,7 +240,8 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
         throw new Error(
           failureOutput(
             result,
-            "APEXlang runtime validation did not produce authoritative live pass evidence."
+            "APEXlang runtime validation did not produce authoritative live pass evidence.",
+            compatibilityAdvisory
           )
         );
       }
@@ -299,10 +333,12 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
             expectedAppDigest
           });
           if (!createNewTargetProved(proofResult)) {
+            const proofCompatibilityAdvisory = await buildValidationCompatibilityAdvisory(proofResult);
             throw new Error(
               failureOutput(
                 proofResult,
-                "Oracle did not prove that the create-new target is absent from the selected workspace."
+                "Oracle did not prove that the create-new target is absent from the selected workspace.",
+                proofCompatibilityAdvisory
               )
             );
           }
@@ -343,12 +379,14 @@ export function createApexlangTool(overrides: Partial<ApexlangDependencies> = {}
           createNewConfirmed,
           expectedAppDigest
         });
-        const importOutput = processOutput(importResult);
+        const importCompatibilityAdvisory = await buildValidationCompatibilityAdvisory(importResult);
+        const importOutput = processOutput(importResult, importCompatibilityAdvisory);
         if (!liveImportPassed(importResult)) {
           throw new Error(
             failureOutput(
               importResult,
-              "APEXlang validate-and-import did not produce authoritative import pass evidence."
+              "APEXlang validate-and-import did not produce authoritative import pass evidence.",
+              importCompatibilityAdvisory
             )
           );
         }
@@ -429,11 +467,21 @@ export {
   IMPORT_CHOICE,
   CREATE_NEW_CHOICE,
   EXPORT_OVERWRITE_GUIDELINE,
+  MASS_VALIDATION_DISTINCT_FILE_THRESHOLD,
+  MASS_VALIDATION_FINDING_THRESHOLD,
+  ORDS_SQLCL_COMPATIBILITY,
+  ORDS_SQLCL_COMPATIBILITY_GUIDELINE,
+  ORDS_SQLCL_COMPATIBILITY_TABLE,
   UPDATE_EXISTING_CHOICE,
   actionWritesProject,
+  buildValidationCompatibilityAdvisory,
+  clearLocalValidationCompatibilityReports,
   confirmationMessage,
   createNewTargetProved,
+  detectValidationCompatibilitySignal,
+  formatValidationCompatibilityAdvisory,
   liveImportPassed,
-  liveValidationPassed
+  liveValidationPassed,
+  renderOrdsSqlclCompatibilityTable
 };
 export type { ApexlangAction };

package/extensions/apexlang/ords-sqlcl-compatibility.json

@@ -0,0 +1,67 @@
+{
+  "schemaVersion": 1,
+  "policy": "advisory-only",
+  "lastReviewed": "2026-07-19",
+  "massValidation": {
+    "minimumFindings": 50,
+    "minimumDistinctFilesForAppWideReports": 5
+  },
+  "caveat": "Oracle publishes minimum APEXlang prerequisites, not an ORDS-to-SQLcl patch certification matrix. Exact SQLcl builds in this table are diagnostic baselines and never validation gates.",
+  "rows": [
+    {
+      "environment": "ORDS before 26.1.1 or APEX before 26.1",
+      "matchMode": "any",
+      "ordsRange": "<26.1.1",
+      "apexRange": "<26.1",
+      "sqlclGuidance": "APEXlang is unsupported; upgrade the server components before changing SQLcl.",
+      "diagnosticSqlclBuild": "",
+      "diagnosticSqlclDownloadUrl": "",
+      "basis": "oracle-confirmed",
+      "sourceUrls": [
+        "https://www.oracle.com/tools/ords/ords-relnotes-26.1.1.html",
+        "https://docs.oracle.com/en/database/oracle/apex/26.1/htmrn/changed-behavior.html"
+      ]
+    },
+    {
+      "environment": "APEX 26.1.x with ORDS 26.1.1 through 26.1.x",
+      "matchMode": "all",
+      "ordsRange": ">=26.1.1 <26.2.0",
+      "apexRange": "26.1.x",
+      "sqlclGuidance": "Oracle minimum: SQLcl 26.1. Diagnostic baseline: 26.1.2.132.1334.",
+      "diagnosticSqlclBuild": "26.1.2.132.1334",
+      "diagnosticSqlclDownloadUrl": "https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-26.1.2.132.1334.zip",
+      "basis": "oracle-minimum-plus-extension-advisory",
+      "sourceUrls": [
+        "https://docs.oracle.com/en/database/oracle/sql-developer-command-line/26.1/sqcug/prerequisites-apexlang.html",
+        "https://www.oracle.com/tools/sqlcl/sqlcl-relnotes-26.1.2.html"
+      ]
+    },
+    {
+      "environment": "APEX 26.1.x with ORDS 26.2.x",
+      "matchMode": "all",
+      "ordsRange": ">=26.2.0 <26.3.0",
+      "apexRange": "26.1.x",
+      "sqlclGuidance": "Oracle does not mandate SQLcl 26.2. On mass findings, compare with diagnostic baseline 26.1.2.132.1334.",
+      "diagnosticSqlclBuild": "26.1.2.132.1334",
+      "diagnosticSqlclDownloadUrl": "https://download.oracle.com/otn_software/java/sqldeveloper/sqlcl-26.1.2.132.1334.zip",
+      "basis": "extension-advisory",
+      "sourceUrls": [
+        "https://docs.oracle.com/en/database/oracle/sql-developer-command-line/26.1/sqcug/prerequisites-apexlang.html",
+        "https://www.oracle.com/tools/sqlcl/sqlcl-downloads.html"
+      ]
+    },
+    {
+      "environment": "Other or newer APEX, MMD, or ORDS release lines",
+      "matchMode": "fallback",
+      "ordsRange": "other",
+      "apexRange": "other",
+      "sqlclGuidance": "Verify current Oracle release documentation and use SQLcl compiler metadata that supports the app mmdVersion.",
+      "diagnosticSqlclBuild": "",
+      "diagnosticSqlclDownloadUrl": "",
+      "basis": "verify-current-docs",
+      "sourceUrls": [
+        "https://docs.oracle.com/en/database/oracle/apex/26.1/apxdc/using-sqlcl-apexlang.html"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-apexlang",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "APEXlang support for pi, powered by Oracle's public APEXlang skill.",
   "type": "module",
   "license": "UPL-1.0",