@clearlydev/nx-archweave 0.0.0-stage → 0.1.1

package/dist/generators/doctor/integration-report.js

@@ -0,0 +1,70 @@
+import { computeOverallStatus } from '@nx-archweave/shared';
+import { runDoctorChecks } from '@nx-archweave/template-engine';
+import { detectIntegrationsDrift, readEnabledIntegrationIds, buildIntegrationDoctorChecks, classifyIntegrationDrift, loadManifest, detectWorkspacePackage, verifyClaudeMarketplacePlugin, PLUGIN_CATALOG, } from '@nx-archweave/integrations';
+import { createIntegrationsCompositionRoot, } from "../../runtime/integrations-composition-root.js";
+import { diskRunNx } from "../shared/run-nx.js";
+// Only claude-code is a supported target for now — doctor
+// does not yet accept a --target option, so this is the one hardcoded value.
+const DOCTOR_TARGET_ENVIRONMENT = 'claude-code';
+export async function buildDoctorReportWithIntegrations(root, options = {}, deps = {}) {
+    const integrationsRoot = deps.integrationsRoot ?? createIntegrationsCompositionRoot();
+    const baseReport = runDoctorChecks(root);
+    const declaredIds = readEnabledIntegrationIds(root);
+    const runNx = diskRunNx(root);
+    const driftResults = await detectIntegrationsDrift({
+        workspaceRoot: root,
+        targetEnvironment: DOCTOR_TARGET_ENVIRONMENT,
+        declaredIds,
+        integrations: integrationsRoot.listIntegrations(),
+        runNx,
+    });
+    // Without --live-integrations: no ReadOnlyCommandRunner call happens at
+    // all — doctor stays fast and available even where the claude CLI is not
+    // installed, trusting the recorded manifest state exactly as before.
+    const finalDriftResults = options.liveIntegrations
+        ? await applyLiveVerification(driftResults, {
+            root,
+            declaredIds,
+            runner: integrationsRoot.runner,
+            runNx,
+        })
+        : driftResults;
+    const integrationChecks = buildIntegrationDoctorChecks(finalDriftResults);
+    const checks = [...baseReport.checks, ...integrationChecks];
+    return { checks, overallStatus: computeOverallStatus(checks) };
+}
+// Re-derives each catalog plugin's drift result using a live verification signal in
+// place of the manifest's frozen `verification` field — every other input to
+// classifyIntegrationDrift (declared, detected) is unchanged, so this never
+// duplicates the classification logic itself, only substitutes one input to
+// it. This is still fully read-only: no manifest or config write, no repair.
+async function applyLiveVerification(driftResults, ctx) {
+    const context = { workspaceRoot: ctx.root, targetEnvironment: DOCTOR_TARGET_ENVIRONMENT };
+    const manifest = loadManifest(ctx.root);
+    const live = new Map();
+    // Only the plugins doctor reports on, and only those this target can verify — each live
+    // check is one `claude plugin list` call.
+    const reported = new Set(driftResults.map((result) => result.id));
+    for (const entry of PLUGIN_CATALOG) {
+        if (!reported.has(entry.id) || entry.hosts[DOCTOR_TARGET_ENVIRONMENT] === undefined)
+            continue;
+        const existingEntry = manifest.integrations[entry.id];
+        const detected = await detectWorkspacePackage(entry, context);
+        const { result: liveVerification } = await verifyClaudeMarketplacePlugin(entry, { runner: ctx.runner }, context);
+        // A stale recorded "passed" must never survive a current live failure —
+        // the live result always wins over the recorded one
+        // when --live-integrations is set, never the other way around.
+        const liveEntry = existingEntry
+            ? { ...existingEntry, verification: liveVerification.verified ? 'passed' : 'failed' }
+            : existingEntry;
+        live.set(entry.id, classifyIntegrationDrift({
+            id: entry.id,
+            installable: true,
+            declared: ctx.declaredIds.includes(entry.id),
+            manifestEntry: liveEntry,
+            detected,
+            runNx: ctx.runNx,
+        }));
+    }
+    return driftResults.map((result) => live.get(result.id) ?? result);
+}

package/dist/generators/doctor/render.js

@@ -0,0 +1,10 @@
+export function renderDoctorReport(report) {
+    const lines = [`Overall status: ${report.overallStatus}`, ''];
+    for (const check of report.checks) {
+        lines.push(`[${check.status.toUpperCase()}] ${check.label}: ${check.message}`);
+        if (check.suggestedAction) {
+            lines.push(`  → ${check.suggestedAction}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/generators/entity/generator.js

@@ -0,0 +1,395 @@
+// src/generators/slice/core.ts
+import { join } from "node:path";
+
+// ../template-engine/dist/fsd/slice-rules.js
+function toCamelCase(kebabName) {
+  return kebabName.split("-").filter((part) => part.length > 0).map((part, index) => index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function resolveSlicePublicApiName(name, publicApiName) {
+  return publicApiName ?? toCamelCase(name);
+}
+var IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var RESERVED_WORDS = /* @__PURE__ */ new Set([
+  "await",
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "implements",
+  "import",
+  "in",
+  "instanceof",
+  "interface",
+  "let",
+  "new",
+  "null",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "return",
+  "static",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield"
+]);
+function isUsableSliceApiName(candidate) {
+  return IDENTIFIER_PATTERN.test(candidate) && !RESERVED_WORDS.has(candidate);
+}
+var ESSENCE_SEGMENT_NAMES = [
+  "components",
+  "hooks",
+  "helpers",
+  "utils",
+  "types",
+  "constants",
+  "consts",
+  "interfaces",
+  "enums",
+  "modals",
+  "stores",
+  "services"
+];
+function isEssenceSegmentName(name) {
+  return ESSENCE_SEGMENT_NAMES.includes(name);
+}
+var SEGMENT_NAME_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+// src/generators/shared/toolkit-config-file.ts
+var TOOLKIT_CONFIG_PATH = "toolkit.config.json";
+function readToolkitConfigFile(tree) {
+  const raw = tree.read(TOOLKIT_CONFIG_PATH, "utf-8");
+  if (raw === null) return { raw: null, parsed: null };
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      raw,
+      parsed: typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null
+    };
+  } catch {
+    return { raw, parsed: null };
+  }
+}
+function readToolkitConfig(tree) {
+  return readToolkitConfigFile(tree).parsed;
+}
+function resolveLocaleOption(option, config) {
+  if (option) return option;
+  const locale = config?.["locale"];
+  return locale === "ko" || locale === "en" ? locale : "en";
+}
+var RECORDED_FRONTENDS = ["react-vite", "next", "none"];
+
+// src/generators/shared/frontend-app.ts
+import { getProjects } from "@nx/devkit";
+
+// src/generators/shared/project-type.ts
+import { parseJson } from "@nx/devkit";
+function resolveProjectType(tree, root, declared) {
+  if (declared) return declared === "library" ? "library" : "application";
+  const prefix = root === "" || root === "." ? "" : `${root}/`;
+  if (tree.exists(`${prefix}tsconfig.lib.json`)) return "library";
+  if (tree.exists(`${prefix}tsconfig.app.json`)) return "application";
+  const raw = tree.read(`${prefix}package.json`, "utf-8");
+  if (raw === null) return "library";
+  try {
+    const manifest = parseJson(raw);
+    if (manifest && !["exports", "main", "module", "bin"].some((key) => Boolean(manifest[key]))) return "application";
+  } catch {
+  }
+  return "library";
+}
+
+// src/generators/shared/frontend-app.ts
+var baseNameOf = (root) => root.split("/").pop() ?? root;
+function isEndToEnd(root) {
+  const dir = baseNameOf(root);
+  return dir === "e2e" || dir.endsWith("-e2e");
+}
+function isBackend(root, config) {
+  return baseNameOf(root) === "api" || (config.tags ?? []).includes("scope:backend");
+}
+function sourceRootOf(config) {
+  if (config.sourceRoot) return config.sourceRoot;
+  return config.root === "" || config.root === "." ? "src" : `${config.root}/src`;
+}
+function resolveFrontendApp(tree, explicitProject) {
+  let projects;
+  try {
+    projects = getProjects(tree);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const pathMatch = /Cannot parse ([^:]+):/.exec(message);
+    return { kind: "invalid-project-json", detail: pathMatch ? pathMatch[1] : message };
+  }
+  const found = (project2, config2) => ({
+    kind: "found",
+    project: project2,
+    root: config2.root,
+    sourceRoot: sourceRootOf(config2)
+  });
+  if (explicitProject !== void 0) {
+    const config2 = projects.get(explicitProject);
+    return config2 ? found(explicitProject, config2) : { kind: "not-found", project: explicitProject };
+  }
+  const eligible = [...projects.entries()].filter(([, config2]) => !isEndToEnd(config2.root) && !isBackend(config2.root, config2));
+  const declared = eligible.filter(([, config2]) => config2.projectType === "application");
+  const inferred = eligible.filter(
+    ([, config2]) => config2.projectType === void 0 && config2.root !== "" && config2.root !== "." && resolveProjectType(tree, config2.root, void 0) === "application"
+  );
+  const candidates = (declared.length > 0 ? declared : inferred).sort(([a], [b]) => a.localeCompare(b));
+  if (candidates.length === 0) return { kind: "none" };
+  if (candidates.length > 1) return { kind: "ambiguous", candidates: candidates.map(([name]) => name) };
+  const [project, config] = candidates[0];
+  return found(project, config);
+}
+
+// src/generators/shared/template-files.ts
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { generateFiles } from "@nx/devkit";
+import { createTree } from "@nx/devkit/testing";
+function generatorFilesDir(generator, fromUrl) {
+  for (const relative of [`../${generator}/files`, `./generators/${generator}/files`]) {
+    const dir = fileURLToPath(new URL(relative, fromUrl));
+    if (existsSync(dir)) return dir;
+  }
+  throw new Error(`The "${generator}" generator's template files are missing next to ${fileURLToPath(fromUrl)}`);
+}
+function renderTemplateFiles(srcFolder, target, substitutions) {
+  const scratch = createTree();
+  const seeded = new Set(scratch.listChanges().map((change) => change.path));
+  generateFiles(scratch, srcFolder, target, substitutions);
+  return scratch.listChanges().flatMap(
+    (change) => change.type === "CREATE" && change.content !== null && !seeded.has(change.path) ? [{ filePath: change.path, content: change.content.toString("utf-8") }] : []
+  ).sort((a, b) => a.filePath.localeCompare(b.filePath));
+}
+
+// src/generators/slice/core.ts
+function composeSlice(input) {
+  const files = generatorFilesDir("slice", import.meta.url);
+  const directory = `${input.sourceRoot}/${input.layerDirName}/${input.name}`;
+  const shared = input.layer === "shared";
+  const values = {
+    name: input.name,
+    publicApiName: input.publicApiName,
+    layer: input.layer,
+    locale: input.locale,
+    modulePath: shared ? `./${input.name}` : `./model/${input.name}`
+  };
+  const module = renderTemplateFiles(join(files, "module"), shared ? directory : `${directory}/model`, values).sort((a, b) => Number(a.filePath.endsWith(".spec.ts")) - Number(b.filePath.endsWith(".spec.ts")));
+  const segments = shared ? [] : Array.from(new Set(input.segments)).filter((segment) => segment !== "model").flatMap((segment) => renderTemplateFiles(join(files, "segment"), `${directory}/${segment}`, { ...values, segment }));
+  return {
+    directory,
+    publicApiName: input.publicApiName,
+    files: [...renderTemplateFiles(join(files, "index"), directory, values), ...module, ...segments]
+  };
+}
+var KEBAB_CASE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function layerDirNameFor(layer, frontend) {
+  return layer === "pages" && frontend === "next" ? "_pages" : layer;
+}
+function layerDirFor(layer, sourceRoot, frontend = "react-vite") {
+  return `${sourceRoot}/${layerDirNameFor(layer, frontend)}`;
+}
+var NEXT_CONFIG_FILES = ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"];
+function resolveFrontendForApp(option, config, appRoot, tree) {
+  if (option === "react-vite" || option === "next") return option;
+  const recorded = config?.["frontend"];
+  if (typeof recorded === "string" && RECORDED_FRONTENDS.includes(recorded) && recorded !== "none") {
+    return recorded;
+  }
+  const prefix = appRoot === "" || appRoot === "." ? "" : `${appRoot}/`;
+  return NEXT_CONFIG_FILES.some((file) => tree.exists(`${prefix}${file}`)) ? "next" : "react-vite";
+}
+function listFilesUnder(tree, dir, prefix = "") {
+  return tree.children(dir).flatMap((child) => {
+    const path = `${dir}/${child}`;
+    return tree.isFile(path) ? [`${prefix}${child}`] : listFilesUnder(tree, path, `${prefix}${child}/`);
+  });
+}
+function computeSliceAction(tree, plan) {
+  if (!tree.exists(plan.directory)) return "created";
+  const expectedNames = plan.files.map((f) => f.filePath.slice(plan.directory.length + 1)).sort();
+  const actualNames = listFilesUnder(tree, plan.directory).sort();
+  if (actualNames.length !== expectedNames.length || !actualNames.every((n, i) => n === expectedNames[i])) {
+    return "skipped";
+  }
+  const allMatch = plan.files.every((f) => tree.read(f.filePath, "utf-8") === f.content);
+  return allMatch ? "unchanged" : "skipped";
+}
+function refusal(reason, dryRun, layer, name, app, extra = {}) {
+  const layerDir = layerDirFor(layer, app.sourceRoot);
+  return {
+    dryRun,
+    layer,
+    name,
+    project: app.project,
+    layerDir,
+    directory: `${layerDir}/${name}`,
+    publicApiName: null,
+    refused: true,
+    refusalReason: reason,
+    action: null,
+    files: [],
+    ...extra
+  };
+}
+function runFsdSlice(tree, layer, options) {
+  const dryRun = options.dryRun ?? false;
+  const unresolved = { project: null, sourceRoot: "<app>/src" };
+  if (!KEBAB_CASE.test(options.name)) {
+    return refusal("invalid-name", dryRun, layer, options.name, unresolved);
+  }
+  if (!isUsableSliceApiName(resolveSlicePublicApiName(options.name, options.publicApiName))) {
+    return refusal("invalid-public-api-name", dryRun, layer, options.name, unresolved);
+  }
+  if (layer === "shared" && isEssenceSegmentName(options.name)) {
+    return refusal("segment-by-essence", dryRun, layer, options.name, unresolved);
+  }
+  const segments = Array.from(new Set(options.segments ?? []));
+  if (segments.length > 0 && layer === "shared") {
+    return refusal("segments-on-shared", dryRun, layer, options.name, unresolved);
+  }
+  const badSegment = segments.find((segment) => !SEGMENT_NAME_PATTERN.test(segment));
+  if (badSegment !== void 0) return refusal("invalid-segment", dryRun, layer, options.name, unresolved, { detail: badSegment });
+  const essenceSegment = segments.find((segment) => isEssenceSegmentName(segment));
+  if (essenceSegment !== void 0) return refusal("segment-by-essence", dryRun, layer, options.name, unresolved, { detail: essenceSegment });
+  const app = resolveFrontendApp(tree, options.project);
+  if (app.kind === "not-found") return refusal("project-not-found", dryRun, layer, options.name, { project: app.project, sourceRoot: unresolved.sourceRoot });
+  if (app.kind === "ambiguous") return refusal("ambiguous-frontend", dryRun, layer, options.name, unresolved, { candidates: app.candidates });
+  if (app.kind === "invalid-project-json") return refusal("invalid-project-json", dryRun, layer, options.name, unresolved, { detail: app.detail });
+  if (app.kind === "none") return refusal("no-frontend-app", dryRun, layer, options.name, unresolved);
+  const config = readToolkitConfig(tree);
+  const frontend = resolveFrontendForApp(options.frontend, config, app.root, tree);
+  const layerDir = layerDirFor(layer, app.sourceRoot, frontend);
+  const locale = resolveLocaleOption(options.locale, config);
+  const plan = composeSlice({
+    layer,
+    name: options.name,
+    publicApiName: resolveSlicePublicApiName(options.name, options.publicApiName),
+    locale,
+    sourceRoot: app.sourceRoot,
+    layerDirName: layerDirNameFor(layer, frontend),
+    segments
+  });
+  const action = computeSliceAction(tree, plan);
+  if (action === "created" && !dryRun) {
+    for (const file of plan.files) tree.write(file.filePath, file.content);
+  }
+  return {
+    dryRun,
+    layer,
+    name: options.name,
+    project: app.project,
+    layerDir,
+    directory: plan.directory,
+    publicApiName: plan.publicApiName,
+    refused: false,
+    refusalReason: null,
+    action,
+    files: plan.files
+  };
+}
+
+// src/generators/slice/render.ts
+var ACTION_LINES = {
+  created: "created",
+  unchanged: "unchanged (already matches the generated content)",
+  skipped: "skipped \u2014 a slice with this name already exists with different content"
+};
+function renderSliceReport(report) {
+  const lines = [];
+  const label = `${report.layer} "${report.name}"`;
+  if (report.refused) {
+    lines.push(`${label}: refused \u2014 nothing was written.`);
+    lines.push("");
+    if (report.refusalReason === "invalid-name") {
+      lines.push(`  "${report.name}" is not a valid kebab-case slice name.`);
+      lines.push('  Use lowercase letters, digits, and single hyphens, starting with a letter (e.g. "add-to-cart").');
+    } else if (report.refusalReason === "invalid-public-api-name") {
+      lines.push("  The public API name is not a usable JavaScript identifier (or is a reserved word).");
+      lines.push('  Pass --publicApiName with a valid identifier, e.g. "addToCart" (this also happens when');
+      lines.push('  the slice name camelCases into a reserved word, like "class" or "delete").');
+    } else if (report.refusalReason === "project-not-found") {
+      lines.push(`  --project=${report.project} names no project in this workspace.`);
+    } else if (report.refusalReason === "ambiguous-frontend") {
+      lines.push("  More than one frontend app was found \u2014 rerun with --project=<one of them>:");
+      for (const name of report.candidates ?? []) lines.push(`    - ${name}`);
+    } else if (report.refusalReason === "invalid-project-json") {
+      lines.push(`  A project.json could not be parsed (${report.detail ?? "unknown"}) \u2014 fix it, then rerun.`);
+    } else if (report.refusalReason === "no-frontend-app") {
+      lines.push("  The workspace has no frontend application to hold FSD layers \u2014 create one, or pass --project.");
+    } else if (report.refusalReason === "invalid-segment") {
+      lines.push(`  --segments: "${report.detail ?? ""}" is not a valid segment name.`);
+      lines.push("  Use lowercase letters, digits, and single hyphens, starting with a letter (e.g. ui, api, lib).");
+    } else if (report.refusalReason === "segments-on-shared") {
+      lines.push("  --segments does not apply to shared: a shared segment holds no segments of its own.");
+      lines.push("  Run the generator once per segment instead (e.g. --name=ui, then --name=api).");
+    } else {
+      const offender = report.detail ?? report.name;
+      lines.push(`  "${offender}" names what a segment contains, not what it is for.`);
+      lines.push("  Canonical FSD names segments by purpose \u2014 ui, api, model, lib, config \u2014 so the code stays");
+      lines.push("  findable by what it does (e.g. a date helper lives in shared/lib, a Button in shared/ui).");
+    }
+    return lines.join("\n");
+  }
+  if (report.dryRun) {
+    lines.push("dry-run \u2014 no files were written.");
+    lines.push("");
+  }
+  lines.push(`${label}: ${ACTION_LINES[report.action]}`);
+  if (report.action === "skipped") {
+    lines.push(`  ${report.directory} already exists and does not exactly match the generated content.`);
+    lines.push("  Pick a new slice name (a name collision is a signal to rename, not to merge)");
+    lines.push("  \u2014 or remove the existing directory manually first if you intended to replace it.");
+    return lines.join("\n");
+  }
+  if (report.dryRun) {
+    for (const file of report.files) {
+      lines.push("");
+      lines.push(`${file.filePath}:`);
+      lines.push(file.content);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/generators/shared/dry-run.ts
+function resolveDryRun(options) {
+  return process.env["NX_DRY_RUN"] === "true" || (options.dryRun ?? false);
+}
+
+// src/generators/entity/generator.ts
+async function entityGenerator(tree, options) {
+  console.log(renderSliceReport(runFsdSlice(tree, "entities", { ...options, dryRun: resolveDryRun(options) })));
+}
+var generator_default = entityGenerator;
+export {
+  generator_default as default,
+  entityGenerator
+};