@cassiomc1/forgeloop 1.8.1 → 1.9.0

package/src/core/structural-quality/source-fingerprint.js

@@ -0,0 +1,112 @@
+import { lstat, readdir } from "node:fs/promises";
+import path from "node:path";
+
+import { canonicalFingerprint } from "../artifacts.js";
+import { ensureWithin, readBytes } from "../filesystem.js";
+import { sha256 } from "../manifest.js";
+import { repositoryHead, repositoryStatusEntries } from "../repository.js";
+import { E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE } from "../error-codes.js";
+
+// Provider-owned configuration is bound by the provider scope resolver, not
+// treated as project source. This keeps custom providers independent of
+// Sentrux's optional rules file.
+const IGNORED_DIRECTORIES = new Set([".forgeloop", ".git", ".sentrux", "node_modules"]);
+
+function fingerprintError(message, cause = null) {
+  const error = new Error(message);
+  error.code = E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE;
+  if (cause) error.cause = cause;
+  return error;
+}
+
+async function readMaterialFile(root, relativePath) {
+  const fullPath = ensureWithin(root, relativePath);
+  let info;
+  try {
+    info = await lstat(fullPath);
+  } catch (error) {
+    throw fingerprintError(`Unable to inspect structural-quality source material: ${relativePath}`, error);
+  }
+  if (info.isSymbolicLink()) {
+    throw fingerprintError(`Structural-quality source material uses an unsafe symlink: ${relativePath}`);
+  }
+  if (!info.isFile()) {
+    throw fingerprintError(`Structural-quality source material is not a regular file: ${relativePath}`);
+  }
+  try {
+    return sha256(await readBytes(fullPath));
+  } catch (error) {
+    throw fingerprintError(`Unable to read structural-quality source material: ${relativePath}`, error);
+  }
+}
+
+async function crawlDirectory(root, current = "") {
+  const dirPath = current ? path.join(root, current) : root;
+  let entries;
+  try {
+    entries = await readdir(dirPath, { withFileTypes: true });
+  } catch (error) {
+    throw fingerprintError(`Unable to enumerate structural-quality source material: ${current || "."}`, error);
+  }
+  const files = [];
+  for (const entry of entries) {
+    const rel = current ? path.join(current, entry.name).replaceAll("\\", "/") : entry.name;
+    if (entry.isSymbolicLink()) {
+      throw fingerprintError(`Structural-quality source material uses an unsafe symlink: ${rel}`);
+    }
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRECTORIES.has(entry.name) || rel.startsWith(".forgeloop/")) continue;
+      files.push(...(await crawlDirectory(root, rel)));
+    } else if (entry.isFile()) {
+      if (rel.startsWith(".forgeloop/")) continue;
+      files.push({ path: rel, sha256: await readMaterialFile(root, rel) });
+    } else {
+      throw fingerprintError(`Unsupported structural-quality source material: ${rel}`);
+    }
+  }
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+export async function computeMaterialSourceFingerprint(target) {
+  try {
+    const head = await repositoryHead(target);
+    const statusEntries = await repositoryStatusEntries(target);
+    const filtered = statusEntries
+      .filter((entry) => !entry.path.startsWith(".forgeloop/")
+        && !entry.path.startsWith(".git/")
+        && !entry.path.startsWith(".sentrux/"));
+    const enriched = [];
+    for (const entry of filtered) {
+      let digest = "DELETED";
+      let exists = false;
+      try {
+        await lstat(ensureWithin(target, entry.path));
+        exists = true;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw fingerprintError(`Unable to inspect structural-quality source material: ${entry.path}`, error);
+      }
+      if (exists) {
+        digest = await readMaterialFile(target, entry.path);
+      }
+      enriched.push({
+        path: entry.path,
+        sourcePath: entry.sourcePath ?? null,
+        status: entry.status,
+        digest,
+      });
+    }
+    enriched.sort((left, right) => left.path.localeCompare(right.path));
+    return canonicalFingerprint({
+      kind: "GIT_WORKTREE",
+      head,
+      statusEntries: enriched,
+    });
+  } catch (error) {
+    if (error?.code === E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE) throw error;
+    const files = await crawlDirectory(target);
+    return canonicalFingerprint({
+      kind: "DIRECTORY",
+      files,
+    });
+  }
+}

package/src/core/structural-quality/status.js

@@ -0,0 +1,3 @@
+// Read-only structural-quality projections live in the service so lifecycle,
+// integration, and CLI consumers share one canonical source of truth.
+export { projectStructuralQualityStatus } from "./service.js";

package/src/core/task-paths.js

@@ -26,6 +26,7 @@ export const TASK_ARTIFACT_FILES = Object.freeze({
   responsibility: "responsibility.json",
   verificationScope: "verification-scope.json",
   attestations: "attestations",
+  structuralQuality: "structural-quality",
 });
 
 export const POLICY_ROOT = ".forgeloop/policy";
@@ -156,6 +157,28 @@ export function taskAttestationHistoryDirectory(taskId, verificationCycle) {
   return `${taskAttestationDirectory(taskId)}/history/cycle-${verificationCycle}`;
 }
 
+export function taskStructuralQualityDirectory(taskId) {
+  return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.structuralQuality}`;
+}
+
+export function taskStructuralQualityBaselinePath(taskId) {
+  return `${taskStructuralQualityDirectory(taskId)}/baseline.json`;
+}
+
+export function taskStructuralQualityEvaluationsDirectory(taskId) {
+  return `${taskStructuralQualityDirectory(taskId)}/evaluations`;
+}
+
+export function taskStructuralQualityEvaluationPath(taskId, verificationCycle, attempt) {
+  if (!Number.isInteger(verificationCycle) || verificationCycle < 1) {
+    throw new Error(`Invalid structural quality verification cycle: ${verificationCycle}`);
+  }
+  if (!Number.isInteger(attempt) || attempt < 1) {
+    throw new Error(`Invalid structural quality evaluation attempt: ${attempt}`);
+  }
+  return `${taskStructuralQualityEvaluationsDirectory(taskId)}/cycle-${verificationCycle}-attempt-${attempt}.json`;
+}
+
 export function taskCodeManifestHistoryPath(taskId, verificationCycle) {
   return `${taskAttestationHistoryDirectory(taskId, verificationCycle)}/code-manifest.json`;
 }
@@ -203,6 +226,7 @@ export function buildTaskArtifactPaths(taskId) {
     responsibility: `${dir}/${TASK_ARTIFACT_FILES.responsibility}`,
     verificationScope: `${dir}/${TASK_ARTIFACT_FILES.verificationScope}`,
     attestations: `${dir}/${TASK_ARTIFACT_FILES.attestations}`,
+    structuralQuality: `${dir}/${TASK_ARTIFACT_FILES.structuralQuality}`,
     codeManifest: taskCodeManifestPath(taskId),
     attestationStatement: taskAttestationStatementPath(taskId),
     attestationBundle: taskAttestationBundlePath(taskId),

package/src/core/templates.js

@@ -87,6 +87,7 @@ export const TEMPLATE_PATHS = [
   "schemas/execution-profile-benchmark-scenario.schema.json",
   "schemas/execution-profile-benchmark-run.schema.json",
   "schemas/execution-profile-benchmark-aggregate.schema.json",
+  "schemas/structural-quality.schema.json",
 ];
 
 export function getPackageRoot() {

package/src/integration.d.ts

@@ -60,8 +60,33 @@ export interface ForgeLoopContext {
   verificationExecutionAdapter?: Record<string, unknown>;
   verificationExecutionPolicy?: { requiredIsolation: string };
   usageProvider?: ForgeLoopUsageProvider;
+  structuralQualityProviders?: Readonly<Record<string, ForgeLoopStructuralQualityProvider | ForgeLoopStructuralQualityProviderFactory>>;
 }
 
+export interface ForgeLoopStructuralQualityProviderInput {
+  projectPath: string;
+  taskId: string;
+  timeoutMs: number;
+  maxOutputBytes: number;
+}
+
+export interface ForgeLoopStructuralQualityProvider {
+  id: string;
+  detect(input: ForgeLoopStructuralQualityProviderInput): Promise<Record<string, unknown>> | Record<string, unknown>;
+  scan(input: ForgeLoopStructuralQualityProviderInput): Promise<Record<string, unknown>> | Record<string, unknown>;
+}
+
+export type ForgeLoopStructuralQualityProviderFactory = (input: ForgeLoopStructuralQualityProviderInput) => ForgeLoopStructuralQualityProvider | Promise<ForgeLoopStructuralQualityProvider>;
+
+export declare const STRUCTURAL_QUALITY_ROOT_CAUSES: readonly ["modularity", "acyclicity", "depth", "equality", "redundancy"];
+export declare const STRUCTURAL_QUALITY_MODES: readonly ["off", "observe", "gate"];
+export declare const STRUCTURAL_QUALITY_STATUSES: readonly ["PASS", "FAIL", "BLOCKED", "NOT_OBSERVED"];
+export declare const STRUCTURAL_QUALITY_CHECK_ID: "structural-quality";
+export declare const STRUCTURAL_QUALITY_REQUIREMENT: string;
+export declare function assertStructuralQualityProvider(provider: unknown): ForgeLoopStructuralQualityProvider;
+export declare function normalizeStructuralQualitySnapshot(input: unknown, options?: { projectPath?: string | null }): Record<string, unknown>;
+export declare function normalizeStructuralQualityDetection(input?: Record<string, unknown>, defaults?: Record<string, unknown>): Record<string, unknown>;
+
 export interface ForgeLoopUsageProvider {
   getTaskUsage(input: { projectPath: string; taskId: string }): Promise<ForgeLoopUsage | Record<string, unknown>> | ForgeLoopUsage | Record<string, unknown>;
 }

package/src/integration.js

@@ -45,6 +45,20 @@ export {
 };
 
 export { createForgeLoopContext } from "./core/runtime-context.js";
+export {
+  assertStructuralQualityProvider,
+  createStructuralQualityProviderRegistry,
+  normalizeStructuralQualityDetection,
+  normalizeStructuralQualitySnapshot,
+  resolveStructuralQualityProvider,
+} from "./core/structural-quality/provider.js";
+export {
+  STRUCTURAL_QUALITY_CHECK_ID,
+  STRUCTURAL_QUALITY_MODES,
+  STRUCTURAL_QUALITY_REQUIREMENT,
+  STRUCTURAL_QUALITY_ROOT_CAUSES,
+  STRUCTURAL_QUALITY_STATUSES,
+} from "./core/structural-quality/constants.js";
 export {
   PROFILE_CONTEXT_POLICIES,
   buildExecutionProfileContext,