@cassiomc1/forgeloop 1.12.0 → 1.13.0

package/src/core/java-project.js

@@ -0,0 +1,403 @@
+import { createLanguageProject, JAVA_SOURCE_EXTENSIONS, pathBelongsToRoot, portablePath } from "./multi-language-project.js";
+import { maskBuildScript } from "./build-script.js";
+import { parseXmlStructure } from "./xml-structure.js";
+
+function invalidJava() {
+  return {
+    valid: false,
+    javaPlugin: false,
+    javaPlatform: false,
+    javaCompiler: false,
+    packaging: null,
+    modules: [],
+    includes: [],
+    gradleBuild: false,
+    gradleSettings: false,
+    gradleProperties: false,
+  };
+}
+
+function childNodes(node, name) {
+  return node.children.filter((child) => child.name.toLowerCase() === name.toLowerCase());
+}
+
+function nodesAtPath(root, names) {
+  return names.reduce((nodes, name) => nodes.flatMap((node) => childNodes(node, name)), [root]);
+}
+
+function nodeValues(nodes) {
+  return nodes
+    .filter((node) => node.children.length === 0 && node.text.length <= 256)
+    .map((node) => node.text.trim())
+    .filter(Boolean);
+}
+
+export function parseMavenPom(text) {
+  const document = parseXmlStructure(text);
+  if (!document || document.root.name.toLowerCase() !== "project") return invalidJava();
+  const root = document.root;
+  const packaging = nodeValues(childNodes(root, "packaging"))[0] ?? null;
+  const modules = nodeValues(nodesAtPath(root, ["modules", "module"]));
+  const compilerProperties = ["release", "source", "target"]
+    .some((name) => nodeValues(nodesAtPath(root, ["properties", `maven.compiler.${name}`])).length > 0);
+  const compilerPlugin = [
+    ["build", "plugins", "plugin", "artifactId"],
+    ["build", "pluginManagement", "plugins", "plugin", "artifactId"],
+  ].some((path) => nodeValues(nodesAtPath(root, path)).some((value) => value === "maven-compiler-plugin"));
+  const javaCompiler = compilerProperties || compilerPlugin;
+  const valid = nodeValues(childNodes(root, "artifactId")).length > 0
+    || packaging === "pom"
+    || modules.length > 0
+    || javaCompiler;
+  return { valid, javaPlugin: false, javaPlatform: false, javaCompiler, packaging, modules };
+}
+
+function maskGradleStringsAndComments(text) {
+  let result = "";
+  let state = "code";
+  let quote = null;
+  let escaped = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    const next = text[index + 1];
+    if (state === "string") {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === quote) {
+        state = "code";
+        quote = null;
+      }
+      result += character === "\n" || character === "\r" ? character : " ";
+    } else if (state === "line-comment") {
+      if (character === "\n" || character === "\r") {
+        result += character;
+        state = "code";
+      } else result += " ";
+    } else if (state === "block-comment") {
+      if (character === "*" && next === "/") {
+        result += "  ";
+        index += 1;
+        state = "code";
+      } else result += character === "\n" || character === "\r" ? character : " ";
+    } else if (character === "\"" || character === "'") {
+      result += " ";
+      quote = character;
+      state = "string";
+    } else if (character === "/" && next === "/") {
+      result += "  ";
+      index += 1;
+      state = "line-comment";
+    } else if (character === "/" && next === "*") {
+      result += "  ";
+      index += 1;
+      state = "block-comment";
+    } else {
+      result += character;
+    }
+  }
+  return state === "code" ? result : null;
+}
+
+function stripGradleComments(text) {
+  let result = "";
+  let state = "code";
+  let quote = null;
+  let escaped = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    const next = text[index + 1];
+    if (state === "string") {
+      result += character;
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === quote) {
+        state = "code";
+        quote = null;
+      }
+    } else if (state === "line-comment") {
+      if (character === "\n" || character === "\r") {
+        result += character;
+        state = "code";
+      } else result += " ";
+    } else if (state === "block-comment") {
+      if (character === "*" && next === "/") {
+        result += "  ";
+        index += 1;
+        state = "code";
+      } else result += character === "\n" || character === "\r" ? character : " ";
+    } else if (character === "\"" || character === "'") {
+      result += character;
+      quote = character;
+      state = "string";
+    } else if (character === "/" && next === "/") {
+      result += "  ";
+      index += 1;
+      state = "line-comment";
+    } else if (character === "/" && next === "*") {
+      result += "  ";
+      index += 1;
+      state = "block-comment";
+    } else result += character;
+  }
+  return state === "code" ? result : null;
+}
+
+const JAVA_PLUGIN_IDS = new Set(["java", "java-library", "java-platform", "java-gradle-plugin", "application", "war"]);
+
+function quotedPluginId(rawBlock, start) {
+  const plugin = rawBlock.slice(start).match(/^\s*(?:\(\s*)?["']([^"']+)["']/u)?.[1];
+  return JAVA_PLUGIN_IDS.has(plugin);
+}
+
+function pluginBlockHasJava(rawBlock) {
+  const masked = maskGradleStringsAndComments(rawBlock);
+  if (masked === null) return false;
+  for (const match of masked.matchAll(/\bid\b/gu)) {
+    if (quotedPluginId(rawBlock, match.index + match[0].length)) return true;
+  }
+  return /(?:^|[;{}\n])\s*(?:`(?:java|javaLibrary|javaPlatform|java-gradle-plugin|application|war)`|java|javaLibrary|javaPlatform|java-gradle-plugin|application|war)\s*(?:[;\n}]|$)/mu.test(masked);
+}
+
+function hasJavaPlugin(text) {
+  const masked = maskGradleStringsAndComments(text);
+  if (masked === null) return false;
+  for (const match of masked.matchAll(/\bplugins\s*\{([\s\S]*?)\}/gu)) {
+    const open = match[0].indexOf("{");
+    if (pluginBlockHasJava(text.slice(match.index + open + 1, match.index + match[0].length - 1))) return true;
+  }
+  for (const match of masked.matchAll(/\bapply\s+plugin\s*:\s*/gu)) {
+    const suffix = text.slice(match.index + match[0].length);
+    if (/^['"](?:java|java-library|java-platform|java-gradle-plugin|application|war)['"]/u.test(suffix)) return true;
+  }
+  return false;
+}
+
+function splitGradleArguments(text) {
+  if (text.trim() === "") return [];
+  const parts = [];
+  let start = 0;
+  let quote = null;
+  let escaped = false;
+  let depth = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (quote) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === quote) quote = null;
+      continue;
+    }
+    if (character === "\"" || character === "'") {
+      quote = character;
+    } else if (character === "(" || character === "[" || character === "{") {
+      depth += 1;
+    } else if (character === ")" || character === "]" || character === "}") {
+      depth -= 1;
+      if (depth < 0) return null;
+    } else if (character === "," && depth === 0) {
+      parts.push(text.slice(start, index).trim());
+      start = index + 1;
+    }
+  }
+  if (quote || depth !== 0) return null;
+  parts.push(text.slice(start).trim());
+  return parts.filter(Boolean);
+}
+
+function gradleQuotedValue(value) {
+  const trimmed = value.trim();
+  if (trimmed.length < 2 || !["\"", "'"].includes(trimmed[0]) || trimmed.at(-1) !== trimmed[0]) return null;
+  const quote = trimmed[0];
+  if (trimmed.includes("$")) return null;
+  let result = "";
+  let escaped = false;
+  for (let index = 1; index < trimmed.length; index += 1) {
+    const character = trimmed[index];
+    if (escaped) {
+      result += character;
+      escaped = false;
+    } else if (character === "\\") {
+      escaped = true;
+    } else if (character === quote) {
+      return index === trimmed.length - 1 ? result : null;
+    } else {
+      result += character;
+    }
+  }
+  return null;
+}
+
+function gradleParenthesisEnd(source, open) {
+  let depth = 1;
+  for (let index = open + 1; index < source.length; index += 1) {
+    if (source[index] === "(") depth += 1;
+    else if (source[index] === ")") {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+
+function topLevelGradleIncludeOffsets(source) {
+  const offsets = [];
+  const depths = { braces: 0, parentheses: 0, brackets: 0 };
+  for (let index = 0; index < source.length; index += 1) {
+    const character = source[index];
+    if (character === "{") depths.braces += 1;
+    else if (character === "}") depths.braces = Math.max(0, depths.braces - 1);
+    else if (character === "(") depths.parentheses += 1;
+    else if (character === ")") depths.parentheses = Math.max(0, depths.parentheses - 1);
+    else if (character === "[") depths.brackets += 1;
+    else if (character === "]") depths.brackets = Math.max(0, depths.brackets - 1);
+    if (Object.values(depths).some((depth) => depth !== 0)
+      || !source.startsWith("include", index)
+      || /[A-Za-z0-9_]/u.test(source[index - 1] ?? "")
+      || /[A-Za-z0-9_]/u.test(source[index + 7] ?? "")) continue;
+    offsets.push(index);
+  }
+  return offsets;
+}
+
+function parseGradleIncludeAt(text, source, index) {
+  let cursor = index + 7;
+  while (/\s/u.test(text[cursor] ?? "")) cursor += 1;
+  let body;
+  if (text[cursor] === "(") {
+    const close = gradleParenthesisEnd(source, cursor);
+    if (close < 0) return null;
+    body = text.slice(cursor + 1, close);
+  } else {
+    const end = text.indexOf("\n", cursor);
+    body = text.slice(cursor, end < 0 ? text.length : end);
+  }
+  const commentFreeBody = stripGradleComments(body);
+  const values = commentFreeBody === null ? null : splitGradleArguments(commentFreeBody);
+  if (values === null) return null;
+  const literals = values.map((value) => gradleQuotedValue(value));
+  return literals.some((literal) => literal === null || literal.trim() === "") ? null : literals;
+}
+
+function isStandaloneGradleInclude(source, index) {
+  const statementStart = Math.max(
+    source.lastIndexOf("\n", index - 1),
+    source.lastIndexOf("\r", index - 1),
+    source.lastIndexOf(";", index - 1),
+  ) + 1;
+  return source.slice(statementStart, index).trim() === "";
+}
+
+function isUnbracedGradleControlBody(source, index) {
+  const lineStart = Math.max(source.lastIndexOf("\n", index - 1), source.lastIndexOf("\r", index - 1)) + 1;
+  let previousEnd = lineStart - 1;
+  while (previousEnd >= 0) {
+    const previousStart = Math.max(
+      source.lastIndexOf("\n", previousEnd - 1),
+      source.lastIndexOf("\r", previousEnd - 1),
+    ) + 1;
+    const previousLine = source.slice(previousStart, previousEnd).trim();
+    if (previousLine) {
+      if (previousLine.includes("{")) return false;
+      return /^(?:if|else|for|while|when|switch)\b/u.test(previousLine);
+    }
+    previousEnd = previousStart - 1;
+  }
+  return false;
+}
+
+export function parseGradleSettings(text) {
+  const invalid = {
+    valid: false,
+    javaPlugin: false,
+    javaPlatform: false,
+    javaCompiler: false,
+    packaging: null,
+    modules: [],
+    includes: [],
+    gradleBuild: false,
+    gradleSettings: true,
+    gradleProperties: false,
+  };
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalid;
+  const source = maskGradleStringsAndComments(text);
+  if (source === null) return invalid;
+  const includes = [];
+  for (const offset of topLevelGradleIncludeOffsets(source)) {
+    if (!isStandaloneGradleInclude(source, offset) || isUnbracedGradleControlBody(source, offset)) continue;
+    const literals = parseGradleIncludeAt(text, source, offset);
+    if (literals === null) return invalid;
+    includes.push(...literals);
+  }
+  return { ...invalid, valid: true, includes: [...new Set(includes)] };
+}
+
+export function parseGradleProperties(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidJava();
+  return { ...invalidJava(), valid: true, gradleProperties: true };
+}
+
+export function parseGradleBuild(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidJava();
+  const source = maskGradleStringsAndComments(text);
+  if (source === null) return invalidJava();
+  const javaPlugin = hasJavaPlugin(text);
+  const javaPlatform = javaPlugin && /(?:java-platform|javaPlatform)/u.test(text);
+  return {
+    valid: javaPlugin || javaPlatform,
+    javaPlugin,
+    javaPlatform,
+    javaCompiler: false,
+    packaging: null,
+    modules: [],
+    includes: [],
+    gradleBuild: true,
+    gradleSettings: false,
+    gradleProperties: false,
+  };
+}
+
+export function parseBazelJava(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidJava();
+  const source = maskBuildScript(text);
+  const javaPlugin = source !== null && /\bjava_(?:binary|library|test|import|plugin)\s*\(/u.test(source);
+  return { valid: javaPlugin, javaPlugin, javaPlatform: false, javaCompiler: false, packaging: null, modules: [] };
+}
+
+function hasOwnedJavaSource(sourceFiles, targetRoot, projectRoot, projectRoots) {
+  return sourceFiles.some((file) => JAVA_SOURCE_EXTENSIONS.has(file.extension)
+    && pathBelongsToRoot(portablePath(targetRoot, file.path), projectRoot, projectRoots));
+}
+
+export function inspectJavaProject({ projectRoot, manifestRelative, manifestText, manifestName, targetRoot, sourceFiles, projectRoots }) {
+  const parsed = manifestName === "pom.xml"
+    ? parseMavenPom(manifestText)
+    : manifestName === "build" || manifestName === "build.bazel"
+      ? parseBazelJava(manifestText)
+      : manifestName === "settings.gradle" || manifestName === "settings.gradle.kts"
+        ? parseGradleSettings(manifestText)
+        : manifestName === "gradle.properties"
+          ? parseGradleProperties(manifestText)
+          : parseGradleBuild(manifestText);
+  const javaSource = hasOwnedJavaSource(sourceFiles, targetRoot, projectRoot, projectRoots);
+  const canProvideJavaEvidence = !parsed.gradleSettings && !parsed.gradleProperties;
+  const structurallyValid = parsed.valid || parsed.gradleBuild;
+  const primary = canProvideJavaEvidence && structurallyValid
+    && (javaSource || parsed.javaPlugin || parsed.javaPlatform || parsed.javaCompiler);
+  const primarySignals = primary
+    ? [`${manifestRelative}:${parsed.javaPlatform ? "java-platform" : manifestName === "pom.xml" ? "maven" : "build"}`]
+    : [];
+  const supportingSignals = [];
+  if (javaSource) supportingSignals.push(`${projectRoot === "." ? "source" : `${projectRoot}/source`}:java`);
+  for (const module of parsed.modules) supportingSignals.push(`${manifestRelative}:module=${module}`);
+  for (const include of parsed.includes ?? []) supportingSignals.push(`${manifestRelative}:include=${include}`);
+  return createLanguageProject({
+    kind: "java",
+    root: projectRoot,
+    manifest: manifestRelative,
+    frameworks: primary ? ["java"] : [],
+    primary,
+    primarySignals,
+    supportingSignals,
+    internal: { ...parsed, valid: parsed.valid },
+  });
+}

package/src/core/multi-language-project.js

@@ -0,0 +1,117 @@
+import path from "node:path";
+
+export const LANGUAGE_PROJECT_FILE_KINDS = Object.freeze({
+  "go.mod": ["go"],
+  "go.work": ["go-work"],
+  "tsconfig.json": ["typescript"],
+  "jsconfig.json": ["javascript-config"],
+  "composer.json": ["php"],
+  "pom.xml": ["java-maven"],
+  "build.gradle": ["java-gradle"],
+  "build.gradle.kts": ["java-gradle"],
+  "settings.gradle": ["java-gradle-settings"],
+  "settings.gradle.kts": ["java-gradle-settings"],
+  "gradle.properties": ["java-gradle-properties"],
+  "build": ["java-bazel", "native-bazel"],
+  "build.bazel": ["java-bazel", "native-bazel"],
+  "cmakelists.txt": ["c-cpp-cmake", "swift-cmake"],
+  "meson.build": ["c-cpp-meson", "swift-meson"],
+  "meson_options.txt": ["c-cpp-meson-options"],
+  "makefile": ["c-cpp-make"],
+  "gnumakefile": ["c-cpp-make"],
+  "package.swift": ["swift-package"],
+  "project.pbxproj": ["swift-xcode"],
+});
+
+export const LANGUAGE_SOURCE_EXTENSIONS = Object.freeze(new Set([
+  ".c", ".cc", ".cpp", ".cxx", ".c++",
+  ".go", ".java", ".php", ".sql", ".psql", ".pgsql", ".swift",
+  ".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs",
+]));
+
+export const SQL_SOURCE_EXTENSIONS = Object.freeze(new Set([".sql", ".psql", ".pgsql"]));
+export const C_SOURCE_EXTENSIONS = Object.freeze(new Set([".c"]));
+export const CPP_SOURCE_EXTENSIONS = Object.freeze(new Set([".cc", ".cpp", ".cxx", ".c++", ".C"]));
+export const JAVA_SOURCE_EXTENSIONS = Object.freeze(new Set([".java"]));
+export const PHP_SOURCE_EXTENSIONS = Object.freeze(new Set([".php", ".phtml", ".php3", ".php4", ".php5", ".php7", ".phps"]));
+export const SWIFT_SOURCE_EXTENSIONS = Object.freeze(new Set([".swift"]));
+
+export function languageProjectKinds(fileName) {
+  if (typeof fileName !== "string") return [];
+  const lowerName = fileName.toLowerCase();
+  if (/^tsconfig\.[^/]+\.json$/u.test(lowerName)) return ["typescript"];
+  if (/\.sqlproj$/u.test(lowerName)) return ["sql-project"];
+  return LANGUAGE_PROJECT_FILE_KINDS[lowerName] ?? [];
+}
+
+export function languageSourceExtension(fileName) {
+  if (typeof fileName !== "string") return null;
+  const extension = path.extname(fileName);
+  const normalized = extension === ".C" ? ".C" : extension.toLowerCase();
+  return LANGUAGE_SOURCE_EXTENSIONS.has(normalized.toLowerCase()) ? normalized : null;
+}
+
+export function portablePath(root, absolutePath) {
+  const relative = path.relative(root, absolutePath).split(path.sep).join("/");
+  return relative === "" ? "." : relative;
+}
+
+export function relativeProjectRoots(targetRoot, projectFiles = []) {
+  return [...new Set(projectFiles
+    .map((entry) => portablePath(targetRoot, path.dirname(entry.path)))
+    .filter((root) => root !== ".." && !root.startsWith("../")))].sort((left, right) => left.localeCompare(right));
+}
+
+export function pathBelongsToRoot(relativePath, root, projectRoots = []) {
+  const normalizedPath = relativePath.replaceAll("\\", "/").toLowerCase();
+  const normalizedRoot = root.replaceAll("\\", "/").toLowerCase();
+  if (normalizedRoot !== "."
+    && normalizedPath !== normalizedRoot
+    && !normalizedPath.startsWith(`${normalizedRoot}/`)) return false;
+  return !projectRoots.some((candidate) => {
+    const normalizedCandidate = candidate.replaceAll("\\", "/").toLowerCase();
+    const nested = normalizedRoot === "."
+      ? normalizedCandidate !== "."
+      : normalizedCandidate.startsWith(`${normalizedRoot}/`);
+    return nested
+      && (normalizedPath === normalizedCandidate || normalizedPath.startsWith(`${normalizedCandidate}/`));
+  });
+}
+
+export function sourceFilesUnderRoot(sourceFiles, targetRoot, root, extensions, projectRoots = []) {
+  return sourceFiles.filter((file) => {
+    if (!extensions.has(languageSourceExtension(file.name))) return false;
+    return pathBelongsToRoot(portablePath(targetRoot, file.path), root, projectRoots);
+  });
+}
+
+export function createLanguageProject({
+  kind,
+  root,
+  manifest,
+  frameworks = [],
+  primary = false,
+  primarySignals = [],
+  supportingSignals = [],
+  internal = null,
+}) {
+  return {
+    kind,
+    root,
+    manifest,
+    validManifest: Boolean(internal?.valid ?? primary),
+    primary,
+    frameworks: [...new Set(frameworks)].sort((left, right) => left.localeCompare(right)),
+    primarySignals: [...primarySignals],
+    supportingSignals: [...supportingSignals],
+    internal,
+  };
+}
+
+export function isDirectSourceClaim(claim, extensions) {
+  return extensions.has(path.extname(claim).toLowerCase());
+}
+
+export function isConfigOnlyProject(project) {
+  return !project?.frameworks?.length && !project?.primary;
+}

package/src/core/next-explanation.js

@@ -0,0 +1,63 @@
+const MAX_EXPLANATION_TEXT = 240;
+const MAX_EXPLANATION_REASON_CODE = 96;
+const MAX_EXPLANATION_ARTIFACT_TEXT = 240;
+const MAX_EXPLANATION_REASONS = 3;
+const MAX_EXPLANATION_ARTIFACTS = 6;
+
+const REQUIRED_CHANGES = Object.freeze({
+  E_CONTRACT_STALE: "Refresh the contract-bound checkpoint and route before continuing.",
+  E_ROUTE_STALE: "Re-run the canonical route for the current contract before continuing.",
+  E_REPOSITORY_CHANGED: "Revalidate the repository and record new evidence before continuing.",
+  E_RECEIPT_STALE: "Inspect the receipt boundary and obtain a fresh independently verifiable receipt.",
+  E_RECEIPT_MISSING: "Provide the required task-bound receipt or record the check as unavailable.",
+  E_CHECK_OBSERVATION_REQUIRED: "Run the required check through an observable verification boundary and record its result.",
+  E_TASK_SCOPE_CONFLICT: "Resolve the overlapping task ownership through the canonical task recovery or coordination path.",
+  E_VERIFICATION_EXECUTION_INVALID: "Repair or replace the verification execution boundary before recording evidence.",
+  E_PUBLICATION_REQUIREMENT_PENDING: "Obtain independently verifiable publication evidence; do not infer publication from local checks.",
+});
+
+function bounded(value, limit = MAX_EXPLANATION_TEXT) {
+  const text = String(value ?? "").trim();
+  return text.length <= limit ? text : `${text.slice(0, limit - 1)}…`;
+}
+
+function reasonExplanation(reason) {
+  const source = reason && typeof reason === "object" ? reason : {};
+  const artifacts = [...new Set((Array.isArray(source.artifacts) ? source.artifacts : [])
+    .filter((artifact) => typeof artifact === "string" && artifact.length > 0)
+    .map((artifact) => bounded(artifact, MAX_EXPLANATION_ARTIFACT_TEXT)))]
+    .slice(0, MAX_EXPLANATION_ARTIFACTS);
+  return {
+    code: bounded(source.code ?? "E_NEXT_ACTION_BLOCKED", MAX_EXPLANATION_REASON_CODE),
+    failedInvariant: bounded(source.message),
+    safeArtifacts: artifacts,
+    requiredChange: REQUIRED_CHANGES[source.code] ?? "Satisfy the canonical condition described by this reason before continuing.",
+    evidenceNeeded: artifacts.length > 0
+      ? `Inspect or update only the listed protocol artifacts, then re-run the canonical next action.`
+      : "Provide a fresh, scoped, independently observable result for the blocked condition.",
+  };
+}
+
+export function explainNextAction(result) {
+  const reasons = (Array.isArray(result?.reasons) ? result.reasons : [])
+    .slice(0, MAX_EXPLANATION_REASONS)
+    .map(reasonExplanation);
+  const mutating = (Array.isArray(result?.commandSpecs) ? result.commandSpecs : []).some((spec) => [
+    "advance",
+    "clear-state",
+    "complete",
+    "record-check",
+    "record-diagnosis",
+    "record-intervention",
+    "prepare-completion",
+    "route",
+  ].includes(spec.commandId));
+  return {
+    schemaVersion: 1,
+    summary: bounded(`Next action ${result?.nextAction ?? "UNKNOWN"} is required for phase ${result?.currentPhase ?? "UNKNOWN"}.`),
+    actionKind: mutating ? "MUTATING_COMMAND_MAY_BE_REQUIRED" : "READ_ONLY_OR_HOST_ACTION",
+    requiresExternalAuthority: Boolean(result?.authorityRequired || result?.hostActionRequired || result?.approvalRequired),
+    reasons,
+    bounded: true,
+  };
+}

package/src/core/php-project.js

@@ -0,0 +1,85 @@
+import { createLanguageProject, PHP_SOURCE_EXTENSIONS } from "./multi-language-project.js";
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function invalidComposer() {
+  return {
+    valid: false,
+    name: null,
+    type: null,
+    autoload: false,
+    requirements: [],
+  };
+}
+
+function hasValidComposerSections(value) {
+  const requirementFields = ["require", "require-dev", "replace", "provide", "conflict"];
+  if (requirementFields.some((field) => value[field] !== undefined && !isPlainObject(value[field]))) return false;
+  const autoload = value.autoload === undefined || isPlainObject(value.autoload);
+  const autoloadDev = value["autoload-dev"] === undefined || isPlainObject(value["autoload-dev"]);
+  return autoload && autoloadDev;
+}
+
+function composerStringField(value, field) {
+  if (value[field] === undefined) return null;
+  return typeof value[field] === "string" && value[field].trim() !== "" ? value[field] : undefined;
+}
+
+function hasComposerIdentity(value) {
+  return value.name !== undefined
+    || value.require !== undefined
+    || value.autoload !== undefined
+    || value["autoload-dev"] !== undefined;
+}
+
+function parseComposerValue(value) {
+  if (!isPlainObject(value) || !hasValidComposerSections(value)) return invalidComposer();
+  const name = composerStringField(value, "name");
+  const type = composerStringField(value, "type");
+  if (name === undefined || type === undefined || !hasComposerIdentity(value)) return invalidComposer();
+  const hasPhpIdentity = name !== null || value.require !== undefined || value.autoload !== undefined || value["autoload-dev"] !== undefined;
+  if (!hasPhpIdentity) return invalidComposer();
+  return {
+    valid: true,
+    name,
+    type,
+    autoload: value.autoload !== undefined || value["autoload-dev"] !== undefined,
+    requirements: Object.keys(value.require ?? {}).sort((left, right) => left.localeCompare(right)),
+  };
+}
+
+export function parseComposerJson(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidComposer();
+  try {
+    return parseComposerValue(JSON.parse(text));
+  } catch {
+    return invalidComposer();
+  }
+}
+
+export function phpSourceLooksExecutable(text) {
+  return typeof text === "string" && /<\?(?:php(?:\s|$)|=)/iu.test(text);
+}
+
+export function inspectPhpProject({ projectRoot, manifestRelative, manifestText }) {
+  const parsed = parseComposerJson(manifestText);
+  const primary = parsed.valid;
+  const primarySignals = primary ? [`${manifestRelative}:composer`] : [];
+  const supportingSignals = [];
+  if (parsed.name) supportingSignals.push(`${manifestRelative}:name=${parsed.name}`);
+  if (parsed.type) supportingSignals.push(`${manifestRelative}:type=${parsed.type}`);
+  if (parsed.autoload) supportingSignals.push(`${manifestRelative}:autoload`);
+  for (const requirement of parsed.requirements) supportingSignals.push(`${manifestRelative}:require=${requirement}`);
+  return createLanguageProject({
+    kind: "php",
+    root: projectRoot,
+    manifest: manifestRelative,
+    frameworks: primary ? ["php"] : [],
+    primary,
+    primarySignals,
+    supportingSignals,
+    internal: { ...parsed, phpSourceExtensions: [...PHP_SOURCE_EXTENSIONS] },
+  });
+}