@cassiomc1/forgeloop 1.12.0 → 1.13.0

package/src/core/contract-presets.js

@@ -0,0 +1,82 @@
+import { createContract } from "./contract.js";
+
+const PRESET_DEFINITIONS = Object.freeze({
+  documentation: Object.freeze({
+    objective: "Complete the requested documentation change with verified project facts.",
+    constraints: ["Preserve repository-local instructions and existing public documentation contracts."],
+    risks: [],
+    verification: [{ id: "verify-documentation", text: "Relevant documentation checks pass.", type: "VERIFICATION" }],
+    successCriteria: [{ id: "complete-documentation", text: "The requested documentation change is complete and accurate.", type: "PRODUCT" }],
+    stopConditions: ["A required project fact or source cannot be confirmed."],
+  }),
+  bug: Object.freeze({
+    objective: "Diagnose and correct the requested bug without changing unrelated behavior.",
+    constraints: ["Preserve the existing public contract unless a breaking change is explicitly requested."],
+    risks: [],
+    verification: [{ id: "verify-bug-fix", text: "A focused regression check and proportional regression checks pass.", type: "VERIFICATION" }],
+    successCriteria: [{ id: "complete-bug-fix", text: "The reported behavior is corrected and the regression is covered.", type: "PRODUCT" }],
+    stopConditions: ["The failure cannot be reproduced or narrowed with available evidence."],
+  }),
+  feature: Object.freeze({
+    objective: "Implement the requested feature within the confirmed project scope.",
+    constraints: ["Preserve existing architecture and public contracts unless a change is explicitly requested."],
+    risks: [],
+    verification: [{ id: "verify-feature", text: "Focused behavior checks and proportional regression checks pass.", type: "VERIFICATION" }],
+    successCriteria: [{ id: "complete-feature", text: "The requested feature behavior is implemented and documented where applicable.", type: "PRODUCT" }],
+    stopConditions: ["Required product behavior or acceptance facts remain unresolved."],
+  }),
+  release: Object.freeze({
+    objective: "Prepare the requested release with independently verified artifact and publication evidence.",
+    constraints: [
+      "Do not publish, deploy, or mutate external release state without explicit authority.",
+      "Separate local checks, repository integration, publication, and deployment evidence.",
+    ],
+    risks: ["publication"],
+    verification: [{ id: "verify-release", text: "Release identity, package/artifact integrity, and required checks are independently verified.", type: "VERIFICATION" }],
+    successCriteria: [{
+      id: "publish-release",
+      text: "The requested release publication status is independently verified.",
+      type: "PUBLICATION",
+      requiredPublicationStatus: "published",
+    }],
+    stopConditions: ["Publication authority, target, or identity evidence is not available."],
+  }),
+});
+
+export const CONTRACT_PRESET_IDS = Object.freeze(Object.keys(PRESET_DEFINITIONS));
+
+function normalizedClaims(claims) {
+  return [...new Set((Array.isArray(claims) ? claims : [])
+    .filter((claim) => typeof claim === "string" && claim.trim() !== "")
+    .map((claim) => claim.trim()))];
+}
+
+export function createPresetContract({ taskId, preset, claims = [] } = {}) {
+  if (!Object.prototype.hasOwnProperty.call(PRESET_DEFINITIONS, preset)) {
+    const error = new Error(`Unknown contract preset: ${preset}. Expected one of ${CONTRACT_PRESET_IDS.join(", ")}`);
+    error.code = "E_CONTRACT_PRESET_UNKNOWN";
+    throw error;
+  }
+  const definition = PRESET_DEFINITIONS[preset];
+  const confirmedClaims = normalizedClaims(claims);
+  const unresolvedDecisions = confirmedClaims.length > 0
+    ? []
+    : ["Confirm the concrete deliverables and affected behavior before implementation."];
+  return createContract({
+    taskId,
+    objective: definition.objective,
+    deliverables: confirmedClaims.length > 0 ? confirmedClaims : ["Deliverables confirmed by task scope."],
+    constraints: definition.constraints,
+    risks: definition.risks,
+    verification: definition.verification,
+    successCriteria: definition.successCriteria,
+    stopConditions: definition.stopConditions,
+    unresolvedDecisions,
+    sourceRefs: [`contract-preset:${preset}`],
+  });
+}
+
+export function contractPresetDefinition(preset) {
+  if (!Object.prototype.hasOwnProperty.call(PRESET_DEFINITIONS, preset)) return null;
+  return structuredClone(PRESET_DEFINITIONS[preset]);
+}

package/src/core/error-codes.js

@@ -788,8 +788,8 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
     code: "E_RECONCILE_PHASE_INVALID",
     category: "lifecycle",
     classification: "PUBLIC_STABLE",
-    meaning: "reconcile-closure was invoked for a task that is not EXECUTING or VERIFYING.",
-    safeResolution: "reconcile-closure supports EXECUTING or VERIFYING tasks whose objective is already satisfied.",
+    meaning: "reconcile-closure was invoked for a task that is not EXECUTING, VERIFYING, or REVIEWING.",
+    safeResolution: "reconcile-closure supports EXECUTING, VERIFYING, or REVIEWING tasks whose objective is already satisfied.",
   }),
   E_RECONCILE_UNSUPPORTED_DRIFT: Object.freeze({
     code: "E_RECONCILE_UNSUPPORTED_DRIFT",
@@ -831,7 +831,7 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
     category: "freshness",
     classification: "PUBLIC_STABLE",
     meaning: "The work-state checkpoint must be revalidated before the lifecycle can continue.",
-    safeResolution: "Run forgeloop reconcile-closure for externally satisfied EXECUTING tasks, or inspect the freshness reasons for other drift.",
+    safeResolution: "Run forgeloop reconcile-closure for externally satisfied EXECUTING, VERIFYING, or REVIEWING tasks, or inspect the freshness reasons for other drift.",
   }),
   E_DIAGNOSIS_REQUIRED: Object.freeze({
     code: "E_DIAGNOSIS_REQUIRED",

package/src/core/filesystem.js

@@ -129,7 +129,6 @@ export async function assertSafePath(root, relativePath) {
   }
 
   let existing = destination;
-  let relativeExisting = path.normalize(relativePath);
   while (true) {
     try {
       const info = await lstatWithTransientWindowsRetry(existing);
@@ -137,14 +136,7 @@ export async function assertSafePath(root, relativePath) {
         throw new Error(`Path uses a symlink inside target directory: ${relativePath}`);
       }
       const resolvedRoot = await realpathWithTransientWindowsRetry(absoluteRoot);
-      // Resolve the comparison path from the canonical root. Windows can
-      // return different equivalent spellings (for example, short names or
-      // extended-length prefixes) for the root and a child path when those
-      // paths are canonicalized independently. Reconstructing the child from
-      // the canonical root keeps the comparison in one namespace without
-      // weakening the realpath containment check for junctions or symlinks.
-      const canonicalExisting = path.resolve(resolvedRoot, relativeExisting);
-      const resolvedExisting = await realpathWithTransientWindowsRetry(canonicalExisting);
+      const resolvedExisting = await realpathWithTransientWindowsRetry(existing);
       if (!isPathWithin(resolvedRoot, resolvedExisting)) {
         throw new Error(`Path escapes target directory: ${relativePath}`);
       }
@@ -154,7 +146,6 @@ export async function assertSafePath(root, relativePath) {
       const parent = path.dirname(existing);
       if (parent === existing) throw new Error(`Path does not resolve inside target directory: ${relativePath}`);
       existing = parent;
-      relativeExisting = path.dirname(relativeExisting);
     }
   }
 }

package/src/core/go-project.js

@@ -0,0 +1,206 @@
+import path from "node:path";
+
+import { createLanguageProject, portablePath } from "./multi-language-project.js";
+
+const GO_DIRECTIVE = /^(module|go|toolchain|godebug|require|replace|exclude|retract|tool|ignore)\b/u;
+const GO_WORK_DIRECTIVES = new Set(["go", "toolchain", "godebug", "use", "replace", "tool"]);
+
+function invalidGoResult() {
+  return {
+    valid: false,
+    module: null,
+    goVersion: null,
+    toolchain: null,
+    uses: [],
+    localReplacements: [],
+    ignorePaths: [],
+  };
+}
+
+function stripGoComment(line) {
+  const index = line.indexOf("//");
+  return (index < 0 ? line : line.slice(0, index)).trim();
+}
+
+function parseGoDirective(line) {
+  const block = line.match(/^(module|go|toolchain|godebug|require|replace|exclude|retract|use|tool|ignore)\b\s*\(\s*$/u);
+  const match = line.match(/^(module|go|toolchain|godebug|require|replace|exclude|retract|use|tool|ignore)\b\s*(?:\(([^)]*)\)|(.+))$/u);
+  if (block) return { name: block[1], value: "" };
+  if (!match) return null;
+  return {
+    name: match[1],
+    value: (match[2] ?? match[3] ?? "").trim(),
+  };
+}
+
+function collectGoBlock(lines, start) {
+  const values = [];
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const line = stripGoComment(lines[index]);
+    if (line === ")") return { values, end: index, valid: true };
+    if (line !== "") values.push(line);
+  }
+  return { values, end: lines.length, valid: false };
+}
+
+function validGoDirectiveValue(name, value) {
+  if (!value || /\s{2,}/u.test(value)) return false;
+  if (name === "ignore") {
+    const portable = value.replaceAll("\\", "/");
+    const segments = portable.split("/");
+    return !value.includes("\\")
+      && !portable.startsWith("/")
+      && !/^[A-Za-z]:\//u.test(portable)
+      && !segments.includes("..")
+      && !value.includes("=>");
+  }
+  if (["require", "exclude"].includes(name)) return /^\S+\s+v\S+$/u.test(value);
+  if (name === "replace") return /^\S+(?:\s+v\S+)?\s+=>\s+\S+(?:\s+v\S+)?$/u.test(value);
+  if (name === "retract") return /^\S+(?:\s*,\s*\S+)?$/u.test(value);
+  if (name === "godebug") return /^\S+=\S+$/u.test(value);
+  if (name === "tool") return /^\S+(?:\s+v\S+)?$/u.test(value);
+  return true;
+}
+
+function parseGoModMetadataDirective(state, directive) {
+  if (directive.name === "module") {
+    if (state.module !== null || directive.value === "" || /\s/u.test(directive.value)) return false;
+    state.module = directive.value;
+    return true;
+  }
+  if (directive.name === "go") {
+    if (state.goVersion !== null || !/^\d+(?:\.\d+){1,2}$/u.test(directive.value)) return false;
+    state.goVersion = directive.value;
+    return true;
+  }
+  if (directive.name === "toolchain") {
+    if (state.toolchain !== null || !/^\S+$/u.test(directive.value)) return false;
+    state.toolchain = directive.value;
+    return true;
+  }
+  return null;
+}
+
+function parseGoModBlockDirective(lines, index, directive) {
+  const block = collectGoBlock(lines, index);
+  const valid = block.valid && block.values.every((value) => validGoDirectiveValue(directive.name, value));
+  return {
+    valid,
+    end: block.end,
+    ignorePaths: valid && directive.name === "ignore" ? block.values : [],
+  };
+}
+
+function parseGoModLine(lines, index, state) {
+  const line = stripGoComment(lines[index]);
+  if (line === "" || line.startsWith("//")) return { valid: true, end: index, ignorePaths: [] };
+  const directive = parseGoDirective(line);
+  if (!directive || !GO_DIRECTIVE.test(line)) return { valid: false, end: index, ignorePaths: [] };
+  const metadataValid = parseGoModMetadataDirective(state, directive);
+  if (metadataValid !== null) return { valid: metadataValid, end: index, ignorePaths: [] };
+  if (line.endsWith("(")) return parseGoModBlockDirective(lines, index, directive);
+  const valid = validGoDirectiveValue(directive.name, directive.value);
+  return {
+    valid,
+    end: index,
+    ignorePaths: valid && directive.name === "ignore" ? [directive.value] : [],
+  };
+}
+
+export function parseGoMod(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidGoResult();
+  const lines = text.replaceAll("\r\n", "\n").split("\n");
+  const state = { module: null, goVersion: null, toolchain: null, valid: true };
+  const ignorePaths = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const parsed = parseGoModLine(lines, index, state);
+    state.valid &&= parsed.valid;
+    ignorePaths.push(...parsed.ignorePaths);
+    index = parsed.end;
+  }
+  return {
+    valid: state.valid && state.module !== null,
+    module: state.module,
+    goVersion: state.goVersion,
+    toolchain: state.toolchain,
+    uses: [],
+    localReplacements: [],
+    ignorePaths: [...new Set(ignorePaths)],
+  };
+}
+
+export function parseGoWork(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) {
+    return { valid: false, goVersion: null, uses: [] };
+  }
+  const lines = text.replaceAll("\r\n", "\n").split("\n");
+  let goVersion = null;
+  const uses = [];
+  let valid = true;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = stripGoComment(lines[index]);
+    if (line === "") continue;
+    const directive = parseGoDirective(line);
+    if (!directive) {
+      valid = false;
+      continue;
+    }
+    if (directive.name === "go") {
+      if (goVersion !== null || !/^\d+(?:\.\d+){1,2}$/u.test(directive.value)) valid = false;
+      else goVersion = directive.value;
+      continue;
+    }
+    if (directive.name === "toolchain") {
+      if (!/^\S+$/u.test(directive.value)) valid = false;
+      continue;
+    }
+    if (!GO_WORK_DIRECTIVES.has(directive.name)) {
+      valid = false;
+      continue;
+    }
+    if (directive.name !== "use") {
+      if (line.endsWith("(")) {
+        const block = collectGoBlock(lines, index);
+        if (!block.valid || !block.values.every((value) => validGoDirectiveValue(directive.name, value))) valid = false;
+        index = block.end;
+      }
+      continue;
+    }
+    const values = line.endsWith("(") ? collectGoBlock(lines, index) : { values: [directive.value], end: index, valid: true };
+    if (!values.valid || values.values.some((value) => !validGoDirectiveValue("use", value)
+      || value.startsWith("/") || /^[A-Za-z]:/u.test(value))) {
+      valid = false;
+    } else {
+      uses.push(...values.values);
+    }
+    index = values.end;
+  }
+  return { valid: valid && goVersion !== null && uses.length > 0, goVersion, uses: [...new Set(uses)] };
+}
+
+export function inspectGoProject({ projectRoot, manifestRelative, manifestText, manifestName, targetRoot, projectFiles }) {
+  const parsed = manifestName === "go.work" ? parseGoWork(manifestText) : parseGoMod(manifestText);
+  const localUses = manifestName === "go.work"
+    ? parsed.uses.filter((use) => projectFiles.some((file) => file.kind === "go"
+      && parseGoMod(file.text).valid
+      && portablePath(targetRoot, path.dirname(file.path)) === path.posix.normalize(path.posix.join(projectRoot, use))))
+    : [];
+  const primary = parsed.valid && (manifestName === "go.mod" || localUses.length > 0);
+  const primarySignals = primary
+    ? [manifestName === "go.mod" ? `${manifestRelative}:module` : `${manifestRelative}:workspace`]
+    : [];
+  const supportingSignals = [];
+  if (parsed.goVersion) supportingSignals.push(`${manifestRelative}:go=${parsed.goVersion}`);
+  if (parsed.toolchain) supportingSignals.push(`${manifestRelative}:toolchain=${parsed.toolchain}`);
+  for (const use of localUses) supportingSignals.push(`${manifestRelative}:use=${use}`);
+  return createLanguageProject({
+    kind: "go",
+    root: projectRoot,
+    manifest: manifestRelative,
+    frameworks: primary ? ["go"] : [],
+    primary,
+    primarySignals,
+    supportingSignals,
+    internal: { ...parsed, valid: parsed.valid, manifestName, localUses },
+  });
+}