@cassiomc1/forgeloop 1.11.1 → 1.13.0

package/src/config/guides.json

@@ -38,5 +38,53 @@
   "documentation": {
     "path": "ENG/documentation-quality-eng.md",
     "install": true
+  },
+  "flutter": {
+    "path": "ENG/flutter-development-eng.md",
+    "install": true
+  },
+  "dotnet": {
+    "path": "ENG/dotnet-aspnetcore-development-eng.md",
+    "install": true
+  },
+  "nodejs": {
+    "path": "ENG/nodejs-backend-development-eng.md",
+    "install": true
+  },
+  "rust": {
+    "path": "ENG/rust-development-eng.md",
+    "install": true
+  },
+  "c": {
+    "path": "ENG/c-development-eng.md",
+    "install": true
+  },
+  "cpp": {
+    "path": "ENG/cpp-development-eng.md",
+    "install": true
+  },
+  "java": {
+    "path": "ENG/java-development-eng.md",
+    "install": true
+  },
+  "sql": {
+    "path": "ENG/sql-development-eng.md",
+    "install": true
+  },
+  "go": {
+    "path": "ENG/go-development-eng.md",
+    "install": true
+  },
+  "typescript": {
+    "path": "ENG/typescript-development-eng.md",
+    "install": true
+  },
+  "php": {
+    "path": "ENG/php-development-eng.md",
+    "install": true
+  },
+  "swift": {
+    "path": "ENG/swift-development-eng.md",
+    "install": true
   }
 }

package/src/core/build-script.js

@@ -0,0 +1,151 @@
+function quotedValue(text, start) {
+  const quote = text[start];
+  let value = "";
+  let escaped = false;
+  for (let index = start + 1; index < text.length; index += 1) {
+    const character = text[index];
+    if (escaped) {
+      value += character;
+      escaped = false;
+    } else if (character === "\\") {
+      escaped = true;
+    } else if (character === quote) {
+      return { value, next: index + 1 };
+    } else {
+      value += character;
+    }
+  }
+  return null;
+}
+
+function bracketEnd(text, start) {
+  const marker = text.slice(start).match(/^\[(=*)\[/u);
+  if (!marker) return null;
+  const closing = `]${marker[1]}]`;
+  const end = text.indexOf(closing, start + marker[0].length);
+  return end < 0 ? null : { next: end + closing.length };
+}
+
+function maskRange(text, start, end) {
+  return text.slice(start, end).replace(/[^\n\r]/gu, " ");
+}
+
+function skipHashComment(text, start) {
+  const bracket = bracketEnd(text, start + 1);
+  if (text[start + 1] === "[" && bracket) return bracket.next;
+  const lineEnd = text.slice(start).search(/[\n\r]/u);
+  return lineEnd < 0 ? text.length : start + lineEnd;
+}
+
+function skipBuildToken(text, start) {
+  if (text[start] === "#") return { next: skipHashComment(text, start) };
+  if (text[start] === "\"" || text[start] === "'") {
+    const quoted = quotedValue(text, start);
+    return quoted ? { next: quoted.next } : null;
+  }
+  const bracket = bracketEnd(text, start);
+  return bracket ? { next: bracket.next } : { next: start + 1 };
+}
+
+export function maskBuildScript(text) {
+  if (typeof text !== "string") return null;
+  let result = "";
+  for (let index = 0; index < text.length;) {
+    const step = skipBuildToken(text, index);
+    if (!step) return null;
+    result += step.next === index + 1
+      ? text[index]
+      : maskRange(text, index, step.next);
+    index = step.next;
+  }
+  return result;
+}
+
+function callEnd(text, open) {
+  let depth = 1;
+  for (let index = open + 1; index < text.length; index += 1) {
+    const character = text[index];
+    const step = skipBuildToken(text, index);
+    if (!step) return null;
+    if (step.next !== index + 1) {
+      index = step.next - 1;
+      continue;
+    }
+    if (character === "(") depth += 1;
+    else if (character === ")") {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return null;
+}
+
+export function extractBuildCalls(text, names, { caseInsensitive = false } = {}) {
+  if (typeof text !== "string" || !Array.isArray(names)) return null;
+  const wanted = new Set(names.map((name) => caseInsensitive ? name.toLowerCase() : name));
+  const calls = [];
+  for (let index = 0; index < text.length;) {
+    const step = skipBuildToken(text, index);
+    if (!step) return null;
+    if (step.next !== index + 1) {
+      index = step.next;
+      continue;
+    }
+    const name = text.slice(index).match(/^[A-Za-z_][A-Za-z0-9_]*/u)?.[0];
+    if (!name || !wanted.has(caseInsensitive ? name.toLowerCase() : name)) {
+      index += name?.length ?? 1;
+      continue;
+    }
+    let open = index + name.length;
+    while (/\s/u.test(text[open] ?? "")) open += 1;
+    if (text[open] !== "(") {
+      index += name.length;
+      continue;
+    }
+    const close = callEnd(text, open);
+    if (close === null) return null;
+    calls.push({ name, body: text.slice(open + 1, close) });
+    index = close + 1;
+  }
+  return calls;
+}
+
+function splitBuildArguments(text) {
+  const parts = [];
+  let start = 0;
+  const depths = { "(": 0, "[": 0, "{": 0 };
+  for (let index = 0; index < text.length;) {
+    const step = skipBuildToken(text, index);
+    if (!step) return null;
+    if (step.next !== index + 1) {
+      index = step.next;
+      continue;
+    }
+    const character = text[index];
+    if (character === "(" || character === "[" || character === "{") depths[character] += 1;
+    if (character === ")" || character === "]" || character === "}") {
+      const opening = character === ")" ? "(" : character === "]" ? "[" : "{";
+      depths[opening] -= 1;
+      if (depths[opening] < 0) return null;
+    }
+    if (character === "," && Object.values(depths).every((depth) => depth === 0)) {
+      parts.push(text.slice(start, index).trim());
+      start = index + 1;
+    }
+    index += 1;
+  }
+  if (Object.values(depths).some((depth) => depth !== 0)) return null;
+  parts.push(text.slice(start).trim());
+  return parts.filter(Boolean);
+}
+
+export function quotedBuildArguments(text) {
+  const parts = splitBuildArguments(text);
+  if (!parts) return null;
+  return parts.flatMap((part) => {
+    const value = part.length >= 2 && (part[0] === "\"" || part[0] === "'")
+      ? quotedValue(part, 0)
+      : null;
+    return value && value.next === part.length ? [value.value] : [];
+  });
+}

package/src/core/c-cpp-project.js

@@ -0,0 +1,143 @@
+import { createLanguageProject, C_SOURCE_EXTENSIONS, CPP_SOURCE_EXTENSIONS, pathBelongsToRoot, portablePath } from "./multi-language-project.js";
+import { extractBuildCalls, maskBuildScript, quotedBuildArguments } from "./build-script.js";
+
+function invalidNative() {
+  return {
+    valid: false,
+    c: false,
+    cpp: false,
+    make: false,
+  };
+}
+
+function nativeLanguageTokens(text) {
+  const tokens = text.toUpperCase().match(/\b(?:CXX|CPP|C)\b/gu) ?? [];
+  return {
+    c: tokens.includes("C"),
+    cpp: tokens.some((language) => language === "CXX" || language === "CPP"),
+  };
+}
+
+function nativeLanguagesFromCMake(text) {
+  const result = { c: false, cpp: false };
+  const calls = extractBuildCalls(text, ["project", "enable_language"], { caseInsensitive: true });
+  if (!calls) return result;
+  for (const call of calls) {
+    const body = maskBuildScript(call.body);
+    if (body === null) continue;
+    if (call.name.toLowerCase() === "enable_language") {
+      const languages = nativeLanguageTokens(body);
+      result.c ||= languages.c;
+      result.cpp ||= languages.cpp;
+      continue;
+    }
+    const explicit = body.match(/\blanguages?\b([\s\S]*)/iu)?.[1]
+      ?? body.match(/^\s*[^\s]+\s+((?:C|CXX|CPP)\b[\s\S]*)/iu)?.[1]
+      ?? "";
+    const languages = nativeLanguageTokens(explicit);
+    result.c ||= languages.c;
+    result.cpp ||= languages.cpp;
+  }
+  return result;
+}
+
+export function parseCMake(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidNative();
+  const source = maskBuildScript(text);
+  if (source === null) return invalidNative();
+  const languages = nativeLanguagesFromCMake(text);
+  const hasProject = /\bproject\s*\(/iu.test(source);
+  const hasLanguage = /\benable_language\s*\(/iu.test(source);
+  return { valid: hasProject || hasLanguage, ...languages, make: false };
+}
+
+export function parseMeson(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidNative();
+  const calls = extractBuildCalls(text, ["project", "add_languages"]);
+  if (!calls || calls.length === 0) return invalidNative();
+  const languageValues = calls.flatMap((call) => {
+    const values = quotedBuildArguments(call.body) ?? [];
+    return call.name === "project" ? values.slice(1) : values;
+  });
+  return {
+    valid: true,
+    c: languageValues.some((value) => value.toLowerCase() === "c"),
+    cpp: languageValues.some((value) => ["cpp", "cxx"].includes(value.toLowerCase())),
+    make: false,
+  };
+}
+
+export function parseBazelNative(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidNative();
+  const source = maskBuildScript(text);
+  const hasNativeRule = source !== null && /\b(?:cc_|c_)(?:library|binary|test|shared_library|static_library)\s*\(/u.test(source);
+  return { valid: hasNativeRule, c: false, cpp: false, make: false };
+}
+
+export function parseMakefile(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return invalidNative();
+  return { valid: true, c: false, cpp: false, make: true };
+}
+
+function sourceEvidence(sourceFiles, targetRoot, projectRoot, projectRoots) {
+  const c = sourceFiles.some((file) => C_SOURCE_EXTENSIONS.has(file.extension)
+    && pathBelongsToRoot(portablePath(targetRoot, file.path), projectRoot, projectRoots));
+  const cpp = sourceFiles.some((file) => CPP_SOURCE_EXTENSIONS.has(file.extension)
+    && pathBelongsToRoot(portablePath(targetRoot, file.path), projectRoot, projectRoots));
+  return { c, cpp };
+}
+
+function parseNativeManifest(manifestName, manifestText) {
+  const normalizedName = manifestName.toLowerCase();
+  if (normalizedName.includes("cmake")) return parseCMake(manifestText);
+  if (normalizedName.includes("meson")) return parseMeson(manifestText);
+  if (["makefile", "gnumakefile"].includes(normalizedName)) return parseMakefile(manifestText);
+  return parseBazelNative(manifestText);
+}
+
+function nativeFrameworks(parsed, source) {
+  return {
+    c: parsed.c || (parsed.valid && source.c),
+    cpp: parsed.cpp || (parsed.valid && source.cpp),
+  };
+}
+
+function nativePrimarySignals({ manifestRelative, projectRoot, parsed, source, c, cpp }) {
+  if (!c && !cpp) return [];
+  return [
+    ...(c && parsed.c ? [`${manifestRelative}:c`] : []),
+    ...(cpp && parsed.cpp ? [`${manifestRelative}:cpp`] : []),
+    ...(c && source.c && !parsed.c ? [`${projectRoot}/source:c`] : []),
+    ...(cpp && source.cpp && !parsed.cpp ? [`${projectRoot}/source:cpp`] : []),
+  ];
+}
+
+export function inspectNativeProject({ projectRoot, manifestRelative, manifestText, manifestName, targetRoot, sourceFiles, projectRoots }) {
+  const parsed = parseNativeManifest(manifestName, manifestText);
+  const source = sourceEvidence(sourceFiles, targetRoot, projectRoot, projectRoots);
+  const { c, cpp } = nativeFrameworks(parsed, source);
+  const primary = c || cpp;
+  const frameworks = [];
+  if (c) frameworks.push("c");
+  if (cpp) frameworks.push("cpp");
+  const primarySignals = nativePrimarySignals({ manifestRelative, projectRoot, parsed, source, c, cpp });
+  const supportingSignals = parsed.make ? [`${manifestRelative}:make`] : [];
+  return createLanguageProject({
+    kind: "native",
+    root: projectRoot,
+    manifest: manifestRelative,
+    frameworks,
+    primary,
+    primarySignals,
+    supportingSignals,
+    internal: { ...parsed, valid: parsed.valid },
+  });
+}
+
+export function nativeFrameworkForSource(fileName) {
+  const rawExtension = fileName.match(/\.[^.]+$/u)?.[0] ?? "";
+  const extension = rawExtension === ".C" ? ".C" : rawExtension.toLowerCase();
+  if (C_SOURCE_EXTENSIONS.has(extension)) return "c";
+  if (CPP_SOURCE_EXTENSIONS.has(extension)) return "cpp";
+  return null;
+}

package/src/core/cli-command-definitions.js

@@ -324,6 +324,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
       ...CLI_COMMON_OPTIONS,
       ...CLI_TASK_OPTION,
       "--compact": Object.freeze({ targetKey: "compact", parseType: "boolean", takesValue: false, description: "emit a bounded next-action projection" }),
+      "--explain": Object.freeze({ targetKey: "explain", parseType: "boolean", takesValue: false, description: "include bounded read-only blocker and recovery explanation" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],
@@ -991,7 +992,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     writes: [".forgeloop/task-state/<taskKey>/executions/exec-<id>.json", ".forgeloop/task-state/<taskKey>/work-state.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
     removes: [],
     mayExecuteExternalProcess: true,
-    description: "Refreshes the work-state checkpoint of an EXECUTING task whose objective is already satisfied in the current repository, after contract-bound executed evidence, so canonical completion can proceed.",
+    description: "Refreshes the work-state checkpoint of an EXECUTING, VERIFYING, or REVIEWING task whose objective is already satisfied in the current repository, after contract-bound executed evidence, so canonical completion can proceed.",
   }),
   "validate-receipt": Object.freeze({
     name: "validate-receipt",
@@ -1038,6 +1039,8 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
       ...CLI_TASK_OPTION,
       "--claim": Object.freeze({ targetKey: "claims", parseType: "string", takesValue: true, repeatable: true, valueName: "path", missingValueMessage: "--claim requires a path", description: "scoped file path or directory prefix claimed for mutation" }),
       "--contract-file": Object.freeze({ targetKey: "contractFile", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--contract-file requires a path", description: "path to initial contract file" }),
+      "--preset": Object.freeze({ targetKey: "preset", parseType: "string", takesValue: true, valueName: "name", missingValueMessage: "--preset requires a name", description: "bounded contract preset: documentation, bug, feature, or release" }),
+      "--preview": Object.freeze({ targetKey: "preview", parseType: "boolean", takesValue: false, description: "preview the contract without creating lifecycle state" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [".forgeloop/task-state/<taskKey>/task.json", ".forgeloop/task-state/<taskKey>/contract.json"],
@@ -1051,6 +1054,10 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mutation: "READ_ONLY",
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
+      "--phase": Object.freeze({ targetKey: "phase", parseType: "string", takesValue: true, valueName: "phase", missingValueMessage: "--phase requires a phase", description: "only return tasks in this lifecycle phase" }),
+      "--active": Object.freeze({ targetKey: "active", parseType: "boolean", takesValue: false, description: "only return healthy tasks with active ownership and a non-terminal phase" }),
+      "--limit": Object.freeze({ targetKey: "limit", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--limit requires a non-negative integer", description: "maximum tasks to return" }),
+      "--offset": Object.freeze({ targetKey: "offset", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--offset requires a non-negative integer", description: "number of sorted tasks to skip" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],

package/src/core/command-executors.js

@@ -170,7 +170,7 @@ export const COMMAND_EXECUTORS = {
     exitCode: 0,
   }),
   next: async ({ target, packageRoot, options, authorityContext, runtimeContext }) => ({
-    result: await runNext({ target, packageRoot, taskId: options.taskId, authorityContext, runtimeContext, compact: options.compact }),
+    result: await runNext({ target, packageRoot, taskId: options.taskId, authorityContext, runtimeContext, compact: options.compact, explain: options.explain }),
     exitCode: 0,
   }),
   continuity: async ({ target, packageRoot, options }) => ({
@@ -600,11 +600,13 @@ export const COMMAND_EXECUTORS = {
       taskId: options.taskId,
       claims: options.claims,
       contractFile: options.contractFile,
+      preset: options.preset,
+      preview: options.preview,
     }),
     exitCode: 0,
   }),
-  "task-list": async ({ target, packageRoot }) => ({
-    result: await runTaskList({ target, packageRoot }),
+  "task-list": async ({ target, packageRoot, options }) => ({
+    result: await runTaskList({ target, packageRoot, phase: options.phase, active: options.active, limit: options.limit, offset: options.offset }),
     exitCode: 0,
   }),
   "task-show": async ({ target, packageRoot, options }) => ({