@archpilotlabs/archpilot 0.0.16 → 0.0.17

package/dist/archpilot-cli.js

@@ -214124,6 +214124,29 @@ async function countContractFiles(contractsDir) {
     return 0;
   }
 }
+function countGovernedModulesFromConfig(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return 0;
+  }
+  const typed = value;
+  const modules = typed.modules;
+  if (Array.isArray(modules)) {
+    return modules.filter((entry) => typeof entry === "string" && entry.trim().length > 0).length;
+  }
+  if (modules && typeof modules === "object" && !Array.isArray(modules)) {
+    return Object.keys(modules).filter((key) => key.trim().length > 0).length;
+  }
+  return 0;
+}
+async function readGovernedModuleCount(workspaceRoot) {
+  const architecturePath = path5.join(workspaceRoot, ".archpilot", "architecture.json");
+  try {
+    const raw = await import_node_fs5.promises.readFile(architecturePath, { encoding: "utf8" });
+    return countGovernedModulesFromConfig(JSON.parse(raw));
+  } catch {
+    return 0;
+  }
+}
 async function readValidationStatusFromWorkspace(workspaceRoot) {
   const validationStatusPath = path5.join(workspaceRoot, ".archpilot", "validation-status.json");
   let raw;
@@ -214145,8 +214168,9 @@ async function readValidationStatusFromWorkspace(workspaceRoot) {
 async function buildSetupSnapshot(workspaceRoot, validationStatus, options) {
   const archpilotDir = path5.join(workspaceRoot, ".archpilot");
   const contractsDir = path5.join(archpilotDir, "contracts");
-  const [hasArchitectureConfig, hasDependencyRules, hasLayerRules, hasContractsFolder, hasGithubCiWorkflow, detectedBaselineSnapshot, detectedDriftReport, detectedReviewReport] = await Promise.all([
+  const [hasArchitectureConfig, governedModuleCount, hasDependencyRules, hasLayerRules, hasContractsFolder, hasGithubCiWorkflow, detectedBaselineSnapshot, detectedDriftReport, detectedReviewReport] = await Promise.all([
     pathExists3(path5.join(archpilotDir, "architecture.json")),
+    readGovernedModuleCount(workspaceRoot),
     pathExists3(path5.join(archpilotDir, "dependency-rules.json")),
     pathExists3(path5.join(archpilotDir, "layer-rules.json")),
     pathExists3(contractsDir),
@@ -214167,6 +214191,7 @@ async function buildSetupSnapshot(workspaceRoot, validationStatus, options) {
   });
   return {
     hasArchitectureConfig,
+    governedModuleCount,
     hasDependencyRules,
     hasLayerRules,
     hasContractsFolder,
@@ -214204,9 +214229,11 @@ function buildModelFromSnapshot(snapshot, generatedAtUtc, renderContext) {
   const hasMissingDependencyRules = !snapshot.hasDependencyRules;
   const hasMissingLayerRules = !snapshot.hasLayerRules;
   const hasMissingContracts = snapshot.contractFileCount === 0;
+  const hasGovernedModules = snapshot.governedModuleCount > 0;
+  const hasMissingInitialSetupArtifacts = hasMissingDependencyRules || hasMissingLayerRules || hasGovernedModules && hasMissingContracts;
   const missingGithubCiWorkflow = firstSuccessfulValidationCompleted && !snapshot.hasGithubCiWorkflow;
   const missingAdrScaffolds = firstSuccessfulValidationCompleted && snapshot.hasAdrRelatedFindings && snapshot.requiredAdrScaffoldCount > 0;
-  const setupGapCountFromFiles = (hasMissingDependencyRules ? 1 : 0) + (hasMissingLayerRules ? 1 : 0) + (hasMissingContracts ? 1 : 0);
+  const setupGapCountFromFiles = (hasMissingDependencyRules ? 1 : 0) + (hasMissingLayerRules ? 1 : 0) + (hasGovernedModules && hasMissingContracts ? 1 : 0);
   const setupGapCount = typeof setupGapCountFromStatus === "number" ? ensureScore(setupGapCountFromStatus, 0, 1e3) : setupGapCountFromFiles;
   const readinessScore = typeof summary?.readinessScore === "number" ? ensureScore(summary.readinessScore) : snapshot.hasArchitectureConfig ? ensureScore(100 - setupGapCountFromFiles * 20) : 0;
   const architectureHealthScore = typeof summary?.healthScore === "number" ? ensureScore(summary.healthScore) : void 0;
@@ -214243,8 +214270,8 @@ function buildModelFromSnapshot(snapshot, generatedAtUtc, renderContext) {
     {
       id: "contracts",
       label: "Module contracts generated",
-      completed: snapshot.contractFileCount > 0,
-      description: snapshot.contractFileCount > 0 ? `${snapshot.contractFileCount} contract file(s) found.` : "No .archpilot/contracts/*.contract.json files found."
+      completed: !hasGovernedModules || snapshot.contractFileCount > 0,
+      description: !hasGovernedModules ? "No governed modules configured." : snapshot.contractFileCount > 0 ? `${snapshot.contractFileCount} contract file(s) found.` : "No .archpilot/contracts/*.contract.json files found."
     },
     {
       id: "github-ci-governance",
@@ -214376,29 +214403,51 @@ function buildModelFromSnapshot(snapshot, generatedAtUtc, renderContext) {
     });
   } else if (!firstSuccessfulValidationCompleted) {
     pushStage({
-      id: "validate",
-      title: "Validate",
-      description: "Run the first validation pass to establish findings, readiness, and architecture health.",
+      id: hasGovernedModules && hasMissingInitialSetupArtifacts ? "setup" : "validate",
+      title: hasGovernedModules && hasMissingInitialSetupArtifacts ? "Setup" : "Validate",
+      description: hasGovernedModules && hasMissingInitialSetupArtifacts ? "Generate missing setup artifacts before the first validation pass." : "Run the first validation pass to establish findings, readiness, and architecture health.",
       steps: [
-        {
-          id: "run-validation",
-          title: "Run Architecture Validation",
-          description: "Validate the current architecture and generate findings for the Inspector.",
-          priority: 1,
-          action: runValidationAction
-        },
+        ...hasGovernedModules && hasMissingInitialSetupArtifacts ? [
+          {
+            id: "generate-missing-config-contracts",
+            title: "Generate Missing Config & Contracts",
+            description: "Create dependency/layer config and module contracts before first validation.",
+            priority: 1,
+            action: {
+              label: "Generate Missing Config & Contracts",
+              command: "archpilot bootstrap --with-contracts",
+              inspectorActionId: "bootstrap-config-and-contracts",
+              description: "Create missing setup config and module contracts in one deterministic pass."
+            }
+          },
+          {
+            id: "run-validation",
+            title: "Run Architecture Validation",
+            description: "Validate after setup artifacts exist to reduce first-run setup noise.",
+            priority: 2,
+            action: runValidationAction
+          }
+        ] : [
+          {
+            id: "run-validation",
+            title: "Run Architecture Validation",
+            description: "Validate the current architecture and generate findings for the Inspector.",
+            priority: 1,
+            action: runValidationAction
+          }
+        ],
         {
           id: "review-findings",
           title: "Review Findings",
           description: "Use Findings to inspect architecture violations, policy issues, and structural problems.",
-          priority: 2,
+          priority: hasGovernedModules && hasMissingInitialSetupArtifacts ? 3 : 2,
           action: reviewFindingsAction
         },
         {
           id: "fix-structural-issues",
           title: "Fix structural issues",
           description: "Address the most important module boundary and dependency problems first.",
-          priority: 3
+          priority: hasGovernedModules && hasMissingInitialSetupArtifacts ? 4 : 3
         }
       ]
     });
@@ -214568,6 +214617,11 @@ function buildModelFromSnapshot(snapshot, generatedAtUtc, renderContext) {
     label: "Run Smart Init",
     command: "archpilot smart-init-proposal",
     description: "Detect and review a deterministic architecture proposal for this repository."
+  } : !firstSuccessfulValidationCompleted && hasGovernedModules && hasMissingInitialSetupArtifacts ? {
+    label: "Generate Missing Config & Contracts",
+    command: "archpilot bootstrap --with-contracts",
+    inspectorActionId: "bootstrap-config-and-contracts",
+    description: "Create missing setup config and module contracts before the first validation run."
   } : !firstSuccessfulValidationCompleted ? runValidationAction : setupGapCount > 0 ? hasMissingDependencyRules || hasMissingLayerRules ? {
     label: "Bootstrap Missing Config",
     command: "archpilot bootstrap --with-contracts",
@@ -217898,6 +217952,21 @@ var highConfidenceDomainNames = /* @__PURE__ */ new Set([
   "workflow",
   "workflows"
 ]);
+var componentRoleNames = /* @__PURE__ */ new Set([
+  "app",
+  "application",
+  "backend",
+  "bff",
+  "client",
+  "engine",
+  "frontend",
+  "gateway",
+  "ledger",
+  "mobile",
+  "service",
+  "web",
+  "worker"
+]);
 var frontendUtilityDirectoryNames = /* @__PURE__ */ new Set([
   "components",
   "hooks",
@@ -217993,6 +218062,40 @@ function isLowValueModuleName(moduleName) {
 function moduleNameSegments(moduleName) {
   return moduleName.toLowerCase().split(/[\/._-]+/u).map((segment) => segment.trim()).filter((segment) => segment.length > 0);
 }
+function normalizeIdentity(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/gu, "");
+}
+function pathLeafIdentity(value) {
+  const normalized = normalizePath5(value).replace(/\/+$/gu, "");
+  const leaf = normalized.split("/").filter((segment) => segment.length > 0).at(-1) ?? normalized;
+  return normalizeIdentity(leaf);
+}
+function getComponentAlignedEvidence(input2) {
+  const modulePath = normalizePath5(input2.modulePath).replace(/\/+$/gu, "");
+  const moduleNameIdentity = normalizeIdentity(input2.moduleName);
+  const modulePathLeaf = pathLeafIdentity(modulePath);
+  const matchingPath = input2.context?.componentPaths?.map((entry) => normalizePath5(entry).replace(/\/+$/gu, "")).find(
+    (componentPath) => componentPath.length > 0 && componentPath !== "." && (componentPath === modulePath || componentPath.startsWith(`${modulePath}/`) || modulePath.startsWith(`${componentPath}/`))
+  );
+  if (matchingPath) {
+    return `Matches detected component/service/app path ${matchingPath}`;
+  }
+  const matchingName = input2.context?.componentNames?.map(normalizeIdentity).find((identity) => identity.length > 0 && (identity === moduleNameIdentity || identity === modulePathLeaf));
+  if (matchingName) {
+    return `Matches detected component/service/app identity ${input2.moduleName}`;
+  }
+  const matchingResourcePath = input2.context?.resourcePaths?.map((entry) => normalizePath5(entry).replace(/\/+$/gu, "")).find(
+    (resourcePath) => resourcePath.length > 0 && resourcePath !== "." && (resourcePath === modulePath || resourcePath.startsWith(`${modulePath}/`) || modulePath.startsWith(`${resourcePath}/`))
+  );
+  if (matchingResourcePath) {
+    return `Matches detected resource path ${matchingResourcePath}`;
+  }
+  const matchingResourceName = input2.context?.resourceNames?.map(normalizeIdentity).find((identity) => identity.length > 0 && (identity === moduleNameIdentity || identity === modulePathLeaf));
+  if (matchingResourceName) {
+    return `Matches detected resource identity ${input2.moduleName}`;
+  }
+  return void 0;
+}
 function classifyModuleCandidate(input2) {
   const evidence = [];
   const segments = moduleNameSegments(input2.moduleName);
@@ -218001,6 +218104,7 @@ function classifyModuleCandidate(input2) {
   const hasTechnicalLayerName = segments.some((segment) => technicalLayerNames.has(segment));
   const hasSharedInfrastructureName = segments.some((segment) => sharedInfrastructureNames.has(segment));
   const hasDomainName = segments.some((segment) => highConfidenceDomainNames.has(segment));
+  const hasComponentRoleName = segments.some((segment) => componentRoleNames.has(segment));
   const underExplicitArchitectureRoot = ["modules", "features", "domain", "domains"].includes(rootLeaf);
   const underLayerRoot = ["application", "infrastructure"].includes(rootLeaf);
   if (hasTechnicalLayerName) {
@@ -218027,6 +218131,14 @@ function classifyModuleCandidate(input2) {
       selectedByDefault: false
     };
   }
+  if (underExplicitArchitectureRoot && segments.length > 1 && hasComponentRoleName) {
+    evidence.push(`Name '${input2.moduleName}' combines a module root with an app/service/component role`);
+    return {
+      classification: "uncertain",
+      evidence,
+      selectedByDefault: false
+    };
+  }
   if (underExplicitArchitectureRoot && input2.hasSourceFiles && input2.sourceFileCount >= 1) {
     evidence.push(`Located under explicit architecture boundary root ${input2.rootPath}`);
     return {
@@ -218178,15 +218290,24 @@ function makeDetectedModule(workspaceRoot, moduleName, modulePath, rootPath, has
     sourceFileCount
   });
   evidence.push(...candidateClassification.evidence);
+  const componentAlignedEvidence = getComponentAlignedEvidence({
+    moduleName,
+    modulePath,
+    context
+  });
+  if (componentAlignedEvidence) {
+    evidence.push(componentAlignedEvidence);
+  }
   const scope = resolveModuleScope(workspaceRoot, modulePath, context);
+  const classification = componentAlignedEvidence && candidateClassification.classification === "architecture-module" ? "uncertain" : candidateClassification.classification;
   return {
     name: moduleName,
     path: modulePath,
     confidence,
     evidence,
     ...scope ? { scope } : {},
-    classification: candidateClassification.classification,
-    selectedByDefault: candidateClassification.classification === "architecture-module" && candidateClassification.selectedByDefault && confidence !== "low"
+    classification,
+    selectedByDefault: classification === "architecture-module" && candidateClassification.selectedByDefault && confidence !== "low"
   };
 }
 function collectModuleCandidatesFromRoot(workspaceRoot, modulesRootRelative, defaultConfidence, context) {
@@ -218448,7 +218569,11 @@ function detectModules(workspaceRoot, options) {
     projectKinds: options?.projectKinds,
     stacks: options?.stacks,
     ignoreMatcher: options?.ignoreMatcher,
-    projectRoots: options?.projectRoots?.map(normalizePath5)
+    projectRoots: options?.projectRoots?.map(normalizePath5),
+    componentPaths: options?.componentPaths?.map(normalizePath5),
+    componentNames: options?.componentNames,
+    resourcePaths: options?.resourcePaths?.map(normalizePath5),
+    resourceNames: options?.resourceNames
   };
   const explicitRoots = collectExplicitRoots(workspaceRoot, context);
   const usesFrontendAppRouter = options?.stacks?.some((stack) => stack === "nextjs" || stack === "react" || stack === "vue" || stack === "angular");
@@ -218537,7 +218662,11 @@ function detectModuleCandidatesForRoot(workspaceRoot, modulesRootRelative, optio
       projectKinds: options?.projectKinds,
       stacks: options?.stacks,
       ignoreMatcher: options?.ignoreMatcher,
-      projectRoots: options?.projectRoots?.map(normalizePath5)
+      projectRoots: options?.projectRoots?.map(normalizePath5),
+      componentPaths: options?.componentPaths?.map(normalizePath5),
+      componentNames: options?.componentNames,
+      resourcePaths: options?.resourcePaths?.map(normalizePath5),
+      resourceNames: options?.resourceNames
     }
   );
 }
@@ -237005,16 +237134,66 @@ function sortModuleCandidates(candidates) {
     return left.name.localeCompare(right.name);
   });
 }
-function resolveModuleCandidates(detection) {
+function normalizeIdentity2(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/gu, "");
+}
+function normalizeComponentPath(value) {
+  return value.replaceAll("\\", "/").replace(/\/+$/gu, "");
+}
+function isComponentAlignedModuleCandidate(candidate, components, resources = []) {
+  const candidatePath = normalizeComponentPath(candidate.path);
+  const candidateNameIdentity = normalizeIdentity2(candidate.name);
+  const candidatePathLeafIdentity = normalizeIdentity2(candidatePath.split("/").filter((segment) => segment.length > 0).at(-1) ?? candidate.path);
+  const matchesComponent = components.some((component) => {
+    const componentPath = normalizeComponentPath(component.path);
+    if (componentPath.length > 0 && componentPath !== "." && (componentPath === candidatePath || componentPath.startsWith(`${candidatePath}/`) || candidatePath.startsWith(`${componentPath}/`))) {
+      return true;
+    }
+    const componentIdentities = [
+      component.id,
+      component.name,
+      componentPath.split("/").filter((segment) => segment.length > 0).at(-1) ?? ""
+    ].map(normalizeIdentity2);
+    return candidateNameIdentity.length > 0 && componentIdentities.some(
+      (identity) => identity.length > 0 && (identity === candidateNameIdentity || identity === candidatePathLeafIdentity)
+    );
+  });
+  if (matchesComponent) {
+    return true;
+  }
+  return resources.some((resource) => {
+    const resourcePath = typeof resource.path === "string" ? normalizeComponentPath(resource.path) : "";
+    if (resourcePath.length > 0 && resourcePath !== "." && (resourcePath === candidatePath || resourcePath.startsWith(`${candidatePath}/`) || candidatePath.startsWith(`${resourcePath}/`))) {
+      return true;
+    }
+    const resourceIdentities = [
+      resource.id ?? "",
+      resource.name ?? "",
+      resource.provider ?? "",
+      resourcePath.split("/").filter((segment) => segment.length > 0).at(-1) ?? ""
+    ].map(normalizeIdentity2);
+    return candidateNameIdentity.length > 0 && resourceIdentities.some(
+      (identity) => identity.length > 0 && (identity === candidateNameIdentity || identity === candidatePathLeafIdentity)
+    );
+  });
+}
+function resolveModuleCandidates(detection, resources = []) {
   return sortModuleCandidates(
-    (detection.modules?.modules ?? []).map((module2) => ({
-      name: module2.name,
-      path: module2.path,
-      classification: module2.classification,
-      confidence: module2.confidence,
-      evidence: [...module2.evidence],
-      selectedByDefault: module2.selectedByDefault
-    }))
+    (detection.modules?.modules ?? []).map((module2) => {
+      const isComponentOrResourceAligned = isComponentAlignedModuleCandidate(
+        module2,
+        detection.detectedComponents ?? [],
+        resources
+      );
+      return {
+        name: module2.name,
+        path: module2.path,
+        classification: isComponentOrResourceAligned && module2.classification === "architecture-module" ? "uncertain" : module2.classification,
+        confidence: module2.confidence,
+        evidence: isComponentOrResourceAligned ? [...module2.evidence, "Matches detected component/service/app or resource identity; review before governing as a module"] : [...module2.evidence],
+        selectedByDefault: isComponentOrResourceAligned && module2.classification === "architecture-module" ? false : module2.selectedByDefault
+      };
+    })
   );
 }
 function groupModuleCandidates(candidates) {
@@ -237622,15 +237801,6 @@ function buildArchitectureProposal(detection) {
   } else if ((moduleRoots?.length ?? 0) > 0) {
     addEvidence7(evidence, `Detected module roots: ${moduleRoots.join(", ")}`);
   }
-  const moduleCandidates = resolveModuleCandidates(detection);
-  const moduleCandidateGroups = groupModuleCandidates(moduleCandidates);
-  const modules = moduleCandidates.filter((module2) => module2.selectedByDefault).map((module2) => module2.name).filter((name) => name.length > 0);
-  if (moduleCandidates.length > 0) {
-    addEvidence7(evidence, `Detected ${moduleCandidates.length} module candidates`);
-  }
-  if (modules.length > 0) {
-    addEvidence7(evidence, `Preselected ${modules.length} architecture module candidates`);
-  }
   const apiStyle = resolveProposalApiStyle(detection);
   if (apiStyle) {
     addEvidence7(evidence, apiStyle === "none" ? "Detected no public API signals" : `Detected ${apiStyle.toUpperCase()} API`);
@@ -237645,6 +237815,15 @@ function buildArchitectureProposal(detection) {
   const authStyle = apiStyle && apiStyle !== "none" ? "jwt" : "none";
   const components = resolveProposalComponents(detection);
   const resources = resolveProposalResources({ detection, database, apiStyle });
+  const moduleCandidates = resolveModuleCandidates(detection, resources ?? []);
+  const moduleCandidateGroups = groupModuleCandidates(moduleCandidates);
+  const modules = moduleCandidates.filter((module2) => module2.selectedByDefault).map((module2) => module2.name).filter((name) => name.length > 0);
+  if (moduleCandidates.length > 0) {
+    addEvidence7(evidence, `Detected ${moduleCandidates.length} module candidates`);
+  }
+  if (modules.length > 0) {
+    addEvidence7(evidence, `Preselected ${modules.length} architecture module candidates`);
+  }
   if (database && database !== "none") {
     addEvidence7(evidence, `Detected ${database} database`);
   } else if (database === "none") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archpilotlabs/archpilot",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "Executable architecture governance CLI",
   "homepage": "https://archpilot.org",
   "bugs": {