fastscript 3.0.0 → 3.0.1

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "fastscript",
-  "version": "3.0.0",
-  "description": "FastScript v3 universal JS/TS runtime with first-class .fs source.",
+  "version": "3.0.1",
+  "description": "FastScript v3 universal JS/TS runtime with governed compatibility proof and first-class .fs source.",
+  "keywords": [
+    "fastscript",
+    "javascript",
+    "typescript",
+    "tsx",
+    "jsx",
+    "full-stack",
+    "runtime",
+    "framework",
+    "compatibility",
+    "interop",
+    "npm"
+  ],
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "publishConfig": {
@@ -79,6 +92,7 @@
     "test:benchmark-discipline": "node ./scripts/test-benchmark-discipline.mjs",
     "test:regression-guard": "node ./scripts/test-regression-guard.mjs",
     "test:ecosystem-compatibility-contract": "node ./scripts/test-ecosystem-compatibility-contract.mjs",
+    "test:compatibility-matrix": "node ./scripts/test-compatibility-matrix.mjs",
     "test:release-discipline": "node ./scripts/test-release-discipline.mjs",
     "test:validation": "node ./scripts/test-validation.mjs",
     "test:webhook-storage": "node ./scripts/test-webhook-storage.mjs",
@@ -119,6 +133,7 @@
     "sbom:generate": "node ./scripts/generate-sbom.mjs",
     "proof:publish": "node ./scripts/publish-proof-pack.mjs",
     "docs:index": "node ./scripts/build-docs-index.mjs",
+    "compatibility:generate": "node ./scripts/generate-compatibility-matrix.mjs",
     "docs:api-ref": "node ./scripts/generate-api-reference.mjs",
     "plugins:marketplace-sync": "node ./scripts/plugin-marketplace-sync.mjs",
     "security:rotate-secrets": "node ./scripts/secret-rotation.mjs",
@@ -129,7 +144,7 @@
     "kpi:track": "node ./scripts/kpi-track.mjs",
     "deploy:zero-downtime": "node ./scripts/zero-downtime-deploy.mjs",
     "merge:gate": "node ./scripts/release-merge-gate.mjs",
-    "test:core": "npm run test:middleware && npm run test:auth && npm run test:db && npm run test:db-cli && npm run test:validation && npm run test:webhook-storage && npm run test:jobs && npm run test:plugins && npm run test:fs-diag && npm run test:metrics && npm run test:roundtrip && npm run test:compatibility-first-runtime && npm run test:authored-ts-in-fs && npm run test:js-ts-syntax-proof && npm run test:fs-parity-corpus && npm run test:conversion-rollback-manifest && npm run test:toolchain-observability && npm run test:runtime-permissions && npm run test:benchmark-discipline && npm run test:regression-guard && npm run test:ecosystem-compatibility-contract && npm run test:release-discipline && npm run test:sourcemap-fidelity && npm run test:cache-parity && npm run test:typecheck && npm run test:typecheck-depth && npm run test:format-lint && npm run test:style-rules && npm run test:style-primitives && npm run test:routes && npm run test:runtime-contract && npm run test:determinism && npm run test:parser-fuzz && npm run test:security-baseline && npm run test:deploy-adapters && npm run test:interop-matrix && npm run test:vscode-language && npm run test:runtime-context-rules && npm run test:runtime-scope-diagnostics && npm run test:v2:ambient-runtime && npm run test:v2:stdlib-methods && npm run test:v2:stdlib-matrix && npm run test:v2:dom-globals && npm run test:v2:dom-patterns && npm run test:v2:inference-corpus && npm run test:v2:inference-patterns && npm run test:v2:zero-js-app && npm run test:v2:zero-js-corpora && npm run test:conformance",
+    "test:core": "npm run test:middleware && npm run test:auth && npm run test:db && npm run test:db-cli && npm run test:validation && npm run test:webhook-storage && npm run test:jobs && npm run test:plugins && npm run test:fs-diag && npm run test:metrics && npm run test:roundtrip && npm run test:compatibility-first-runtime && npm run test:authored-ts-in-fs && npm run test:js-ts-syntax-proof && npm run test:fs-parity-corpus && npm run test:conversion-rollback-manifest && npm run test:toolchain-observability && npm run test:runtime-permissions && npm run test:benchmark-discipline && npm run test:regression-guard && npm run test:ecosystem-compatibility-contract && npm run test:compatibility-matrix && npm run test:release-discipline && npm run test:sourcemap-fidelity && npm run test:cache-parity && npm run test:typecheck && npm run test:typecheck-depth && npm run test:format-lint && npm run test:style-rules && npm run test:style-primitives && npm run test:routes && npm run test:runtime-contract && npm run test:determinism && npm run test:parser-fuzz && npm run test:security-baseline && npm run test:deploy-adapters && npm run test:interop-matrix && npm run test:vscode-language && npm run test:runtime-context-rules && npm run test:runtime-scope-diagnostics && npm run test:v2:ambient-runtime && npm run test:v2:stdlib-methods && npm run test:v2:stdlib-matrix && npm run test:v2:dom-globals && npm run test:v2:dom-patterns && npm run test:v2:inference-corpus && npm run test:v2:inference-patterns && npm run test:v2:zero-js-app && npm run test:v2:zero-js-corpora && npm run test:conformance",
     "qa:gate": "npm run repo:lock && npm run format:check && npm run lint:fs && npm run typecheck && npm run validate && npm run test:core && npm run smoke:dev && npm run smoke:start",
     "qa:all": "npm run repo:lock && npm run format:check && npm run lint:fs && npm run typecheck && npm run docs:index && npm run docs:api-ref && npm run validate && npm run test:core && npm run smoke:dev && npm run smoke:start && npm run bench:report && npm run benchmark:suite && npm run interop:report && npm run sbom:generate && npm run proof:publish && npm run backup:create && npm run backup:verify",
     "release:patch": "node ./scripts/release.mjs patch",

package/src/compatibility-governance.mjs

@@ -0,0 +1,257 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const REGISTRY_PATH = resolve("spec", "compatibility-registry.json");
+const SUPPORT_MATRIX_PATH = resolve("docs", "SUPPORT_MATRIX.md");
+const REPORT_PATH = resolve(".fastscript", "proofs", "compatibility-registry-report.json");
+const GENERATED_DIR = resolve("src", "generated");
+const GENERATED_MODULE_PATH = resolve(GENERATED_DIR, "compatibility-registry-report.mjs");
+const VALID_STATUSES = new Set(["proven", "supported", "partial", "planned", "blocked"]);
+const CATEGORY_ORDER = [
+  "ecmascript",
+  "typescript",
+  "jsx-tsx",
+  "fastscript-sugar",
+  "modules-interop",
+  "runtime-targets",
+  "framework-patterns",
+  "tooling",
+  "deployment-adapters",
+];
+const CATEGORY_LABELS = {
+  "ecmascript": "ECMAScript Syntax",
+  "typescript": "TypeScript Syntax Erasure",
+  "jsx-tsx": "JSX / TSX",
+  "fastscript-sugar": "FastScript Sugar",
+  "modules-interop": "Modules And Interop",
+  "runtime-targets": "Runtime Targets",
+  "framework-patterns": "Framework Patterns",
+  "tooling": "Tooling",
+  "deployment-adapters": "Deployment Adapters",
+};
+
+function readJson(path, fallback = null) {
+  if (!existsSync(path)) return fallback;
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function stableLineFromVersion(version) {
+  const [major = "0", minor = "0"] = String(version || "0.0.0").split(".");
+  return `${major}.${minor}.x`;
+}
+
+function formatProofId(id) {
+  return `\`${String(id || "").replace(/^artifact:/, "").replace(/^script:/, "script:")}\``;
+}
+
+export function loadCompatibilityRegistry(path = REGISTRY_PATH) {
+  const registry = readJson(path, {});
+  return {
+    governanceTrack: String(registry.governanceTrack || "4.0"),
+    contract: String(registry.contract || ""),
+    entries: Array.isArray(registry.entries) ? registry.entries : [],
+  };
+}
+
+export function loadCompatibilityArtifacts() {
+  return {
+    jsTsProof: readJson(resolve(".fastscript", "proofs", "js-ts-syntax-proof.json"), { status: "missing", cases: [] }),
+    fsParityProof: readJson(resolve(".fastscript", "proofs", "fs-parity-matrix.json"), { status: "missing", results: [] }),
+    interop: readJson(resolve("benchmarks", "interop-latest.json"), { summary: { total: 0, pass: 0, fail: 0 }, cases: [] }),
+  };
+}
+
+export function collectProofMap(pkg, artifacts = loadCompatibilityArtifacts()) {
+  const map = new Map();
+  const artifactIds = [];
+  for (const scriptName of Object.keys(pkg.scripts || {})) {
+    map.set(`script:${scriptName}`, { id: `script:${scriptName}`, status: "configured", kind: "script" });
+  }
+
+  for (const testCase of artifacts.jsTsProof.cases || []) {
+    const id = `artifact:js-ts-syntax-proof:${testCase.id}`;
+    map.set(id, { id, status: testCase.status, kind: "artifact", artifact: "js-ts-syntax-proof", label: testCase.id });
+    if (testCase.status === "pass") artifactIds.push(id);
+  }
+  for (const result of artifacts.fsParityProof.results || []) {
+    const id = `artifact:fs-parity:${result.id}`;
+    map.set(id, { id, status: result.status, kind: "artifact", artifact: "fs-parity", label: result.id });
+    if (result.status === "pass") artifactIds.push(id);
+  }
+  for (const item of artifacts.interop.cases || []) {
+    const id = `artifact:interop:${item.id}`;
+    map.set(id, { id, status: item.status, kind: "artifact", artifact: "interop", label: item.id });
+    if (item.status === "pass") artifactIds.push(id);
+  }
+
+  return { map, artifactIds };
+}
+
+function summarizeByStatus(entries) {
+  const out = {};
+  for (const entry of entries) out[entry.status] = (out[entry.status] || 0) + 1;
+  return out;
+}
+
+function summarizeByCategory(entries) {
+  const out = {};
+  for (const entry of entries) out[entry.category] = (out[entry.category] || 0) + 1;
+  return out;
+}
+
+function normalizeReportForCompare(report) {
+  const clone = JSON.parse(JSON.stringify(report || {}));
+  delete clone.generatedAt;
+  return clone;
+}
+
+function normalizeSupportMatrixForCompare(markdown) {
+  return String(markdown || "").replace(/^- Generated: .*\r?\n/m, "- Generated: <normalized>\n");
+}
+
+export function buildCompatibilityReport({ registry, pkg, artifacts }) {
+  const { map: proofMap } = collectProofMap(pkg, artifacts);
+  const resolvedEntries = registry.entries.map((entry) => ({
+    ...entry,
+    proofDetails: (entry.proofIds || []).map((proofId) => proofMap.get(proofId) || { id: proofId, status: "missing", kind: "unknown" }),
+  }));
+  return {
+    generatedAt: new Date().toISOString(),
+    governanceTrack: registry.governanceTrack,
+    stableLine: stableLineFromVersion(pkg.version),
+    packageVersion: pkg.version,
+    contract: registry.contract,
+    summary: {
+      entries: resolvedEntries.length,
+      byStatus: summarizeByStatus(resolvedEntries),
+      byCategory: summarizeByCategory(resolvedEntries),
+      provenEntries: resolvedEntries.filter((entry) => entry.status === "proven").length,
+    },
+    artifacts: {
+      jsTsSyntaxCases: (artifacts.jsTsProof.cases || []).length,
+      fsParityCases: (artifacts.fsParityProof.results || []).length,
+      interopCases: (artifacts.interop.cases || []).length,
+    },
+    entries: resolvedEntries,
+  };
+}
+
+export function generateSupportMatrixMarkdown(report) {
+  const lines = [
+    "# FastScript Compatibility Matrix",
+    "",
+    `- Generated: ${report.generatedAt}`,
+    `- Current stable line: \`${report.stableLine}\``,
+    `- Governance track: FastScript \`${report.governanceTrack}\` compatibility system`,
+    `- Product contract: ${report.contract}`,
+    `- Proven means: linked automated coverage and CI-enforced release discipline`,
+    "",
+    "## Status Legend",
+    "- `proven`: linked automated coverage exists and release gates fail on regression",
+    "- `supported`: intended support surface with some proof or operational confidence, but not yet fully governed as `proven`",
+    "- `partial`: some known working coverage exists, but not enough to claim full contract safety",
+    "- `planned`: visible compatibility lane targeted for future proof coverage",
+    "- `blocked`: explicitly unsupported or blocked pending design/runtime work",
+    "",
+    "## Summary",
+    `- Registry entries: ${report.summary.entries}`,
+    `- Proven entries: ${report.summary.provenEntries}`,
+    `- JS/TS syntax proof cases: ${report.artifacts.jsTsSyntaxCases}`,
+    `- .fs parity cases: ${report.artifacts.fsParityCases}`,
+    `- Interop cases: ${report.artifacts.interopCases}`,
+    "",
+  ];
+
+  for (const category of CATEGORY_ORDER) {
+    const items = report.entries.filter((entry) => entry.category === category);
+    if (!items.length) continue;
+    lines.push(`## ${CATEGORY_LABELS[category] || category}`);
+    lines.push("| Feature | Status | Proof | Notes |");
+    lines.push("|---|---|---|---|");
+    for (const entry of items) {
+      const proof = entry.proofIds && entry.proofIds.length
+        ? entry.proofIds.map((proofId) => formatProofId(proofId)).join(", ")
+        : "-";
+      const note = entry.docsNote || entry.contractNote || "";
+      lines.push(`| ${entry.feature} | ${entry.status} | ${proof} | ${note.replace(/\|/g, "\\|")} |`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Compatibility Request Lane");
+  lines.push("If valid JS/TS, a framework pattern, or a real migration case fails in `.fs`, treat it as a FastScript compatibility bug and report it through the compatibility intake workflow.");
+  lines.push("");
+  return `${lines.join("\n").trim()}\n`;
+}
+
+export function validateCompatibilityGovernance({ registry, pkg, artifacts, supportMatrix = null, reportJson = null }) {
+  const errors = [];
+  const { map: proofMap, artifactIds } = collectProofMap(pkg, artifacts);
+  const referencedArtifactIds = new Set();
+
+  for (const entry of registry.entries) {
+    if (!entry.id || !entry.category || !entry.feature) errors.push(`registry entry missing id/category/feature: ${JSON.stringify(entry)}`);
+    if (!VALID_STATUSES.has(entry.status)) errors.push(`registry entry has invalid status: ${entry.id} -> ${entry.status}`);
+    if (!Array.isArray(entry.proofIds)) errors.push(`registry entry proofIds must be an array: ${entry.id}`);
+    for (const proofId of entry.proofIds || []) {
+      const resolved = proofMap.get(proofId);
+      if (!resolved) {
+        errors.push(`registry proof id does not resolve: ${entry.id} -> ${proofId}`);
+        continue;
+      }
+      if (proofId.startsWith("artifact:")) referencedArtifactIds.add(proofId);
+      if (entry.status === "proven" && resolved.status !== "pass" && resolved.status !== "configured") {
+        errors.push(`proven registry entry links to non-passing proof: ${entry.id} -> ${proofId} (${resolved.status})`);
+      }
+    }
+    if (entry.status === "proven" && (!entry.proofIds || entry.proofIds.length === 0)) {
+      errors.push(`proven registry entry must link proof ids: ${entry.id}`);
+    }
+  }
+
+  for (const artifactId of artifactIds) {
+    if (!referencedArtifactIds.has(artifactId)) {
+      errors.push(`passing proof artifact is unregistered in compatibility registry: ${artifactId}`);
+    }
+  }
+
+  const expectedReport = buildCompatibilityReport({ registry, pkg, artifacts });
+  const expectedSupportMatrix = generateSupportMatrixMarkdown(expectedReport);
+  const actualSupportMatrix = supportMatrix ?? (existsSync(SUPPORT_MATRIX_PATH) ? readFileSync(SUPPORT_MATRIX_PATH, "utf8") : "");
+  if (normalizeSupportMatrixForCompare(actualSupportMatrix) !== normalizeSupportMatrixForCompare(expectedSupportMatrix)) {
+    errors.push("docs/SUPPORT_MATRIX.md is stale relative to the compatibility registry");
+  }
+
+  const actualReportJson = reportJson ?? readJson(REPORT_PATH, null);
+  if (JSON.stringify(normalizeReportForCompare(actualReportJson || {})) !== JSON.stringify(normalizeReportForCompare(expectedReport))) {
+    errors.push(".fastscript/proofs/compatibility-registry-report.json is stale relative to the compatibility registry");
+  }
+
+  return { errors, expectedReport, expectedSupportMatrix };
+}
+
+export function writeCompatibilityArtifacts({ registry, pkg, artifacts }) {
+  const report = buildCompatibilityReport({ registry, pkg, artifacts });
+  const supportMatrix = generateSupportMatrixMarkdown(report);
+  mkdirSync(resolve("docs"), { recursive: true });
+  mkdirSync(resolve(".fastscript", "proofs"), { recursive: true });
+  mkdirSync(GENERATED_DIR, { recursive: true });
+  writeFileSync(SUPPORT_MATRIX_PATH, supportMatrix, "utf8");
+  writeFileSync(REPORT_PATH, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+  writeFileSync(GENERATED_MODULE_PATH, `export const COMPATIBILITY_REPORT = ${JSON.stringify(report, null, 2)};\nexport default COMPATIBILITY_REPORT;\n`, "utf8");
+  return { report, supportMatrix };
+}
+
+export async function runCompatibilityGovernanceCheck() {
+  const registry = loadCompatibilityRegistry();
+  const pkg = readJson(resolve("package.json"), {});
+  const artifacts = loadCompatibilityArtifacts();
+  const { errors } = validateCompatibilityGovernance({ registry, pkg, artifacts });
+  if (errors.length) {
+    const error = new Error(`compatibility governance failed:\n- ${errors.join("\n- ")}`);
+    error.status = 1;
+    throw error;
+  }
+  console.log("compatibility governance pass");
+}
+

package/src/fs-normalize.mjs

@@ -1,7 +1,8 @@
 import { compileFastScript } from "./fs-parser.mjs";
 
 export function normalizeFastScript(source, options = {}) {
-  const { code } = compileFastScript(source, {
+  const prepared = stripTypeScriptHints(String(source ?? ""));
+  const { code } = compileFastScript(prepared, {
     file: options.file || "",
     mode: options.mode || "lenient",
     recover: options.recover !== false,
@@ -11,7 +12,8 @@ export function normalizeFastScript(source, options = {}) {
 }
 
 export function normalizeFastScriptWithMetadata(source, options = {}) {
-  return compileFastScript(source, {
+  const prepared = stripTypeScriptHints(String(source ?? ""));
+  return compileFastScript(prepared, {
     file: options.file || "",
     mode: options.mode || "lenient",
     recover: options.recover !== false,
@@ -40,7 +42,7 @@ export function stripTypeScriptHints(source) {
       continue;
     }
 
-    if (/^\s*interface\s+[A-Za-z_$][\w$]*\s*[{]/.test(next) || /^\s*enum\s+[A-Za-z_$][\w$]*\s*[{]/.test(next)) {
+    if (/^\s*interface\s+[A-Za-z_$][\w$]*(?:\s*<[^>]+>)?\s*[{]/.test(next) || /^\s*enum\s+[A-Za-z_$][\w$]*\s*[{]/.test(next)) {
       out.push(`// ${next.trim()} (removed by fastscript migrate)`);
       skippingBlock = true;
       const opens = (next.match(/{/g) || []).length;
@@ -49,7 +51,7 @@ export function stripTypeScriptHints(source) {
       continue;
     }
 
-    if (/^\s*type\s+[A-Za-z_$][\w$]*\s*=/.test(next)) {
+    if (/^\s*type\s+[A-Za-z_$][\w$]*(?:\s*<[^>]+>)?\s*=/.test(next)) {
       out.push(`// ${next.trim()} (removed by fastscript migrate)`);
       if (!next.includes(";") && next.includes("{")) {
         skippingBlock = true;