@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/lib/generators/scaffold-generator.js

@@ -1,22 +1,8 @@
-/**
- * Scaffold Generator - Generates VSA feature slice (.NET) and feature page (Next.js) files.
- *
- * Uses existing Handlebars templates from framework/templates/ to generate
- * complete feature structures with one command.
- *
- * @module scaffold-generator
- */
-
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
 import { join, dirname, basename } from 'path';
 import { renderTemplate } from '../../core/templates/template-renderer.js';
 import { resolveFrameworkTemplatePath } from '../../core/templates/template-registry.js';
 
-/**
- * Convert kebab-case to PascalCase.
- * @param {string} str
- * @returns {string}
- */
 function toPascalCase(str) {
   return str
     .split('-')
@@ -24,11 +10,6 @@ function toPascalCase(str) {
     .join('');
 }
 
-/**
- * Convert kebab-case to camelCase.
- * @param {string} str
- * @returns {string}
- */
 function toCamelCase(str) {
   return str
     .split('-')
@@ -36,16 +17,8 @@ function toCamelCase(str) {
     .join('');
 }
 
-/**
- * Normalize a namespace to kebab-case so Handlebars {{pascalCase}} reconstructs it correctly.
- * Handles: PascalCase ("MyBookStore" → "my-book-store"), dot-separated ("My.App" → "my-app"),
- * and already kebab-case pass-through.
- * @param {string} ns
- * @returns {string}
- */
+/** Kebab-case so Handlebars {{pascalCase}} reconstructs it: "MyBookStore" → "my-book-store", "My.App" → "my-app". */
 export function normalizeNamespaceToKebab(ns) {
-  // Split on dots first (My.BookStore → ["My", "BookStore"])
-  // Then split PascalCase on uppercase boundaries (BookStore → Book-Store)
   return ns
     .split('.')
     .map(segment =>
@@ -57,15 +30,8 @@ export function normalizeNamespaceToKebab(ns) {
     .join('-');
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// .NET VSA Scaffold
-// ─────────────────────────────────────────────────────────────────────────────
-
-// Each entry pairs a REGISTRY.json template `id` with the generator-specific
-// output shaping (class-name suffix, target directory). REGISTRY owns the
-// template path; the generator owns where the rendered file lands.
+// REGISTRY.json owns the template path; the generator owns where the rendered file lands.
 
-/** .NET slice-level files (endpoint/handler/request/response/validator). */
 const DOTNET_SLICE_TEMPLATES = [
   { templateId: 'dotnet-feature-endpoint', suffix: 'Endpoint' },
   { templateId: 'dotnet-feature-handler', suffix: 'Handler' },
@@ -74,23 +40,11 @@ const DOTNET_SLICE_TEMPLATES = [
   { templateId: 'dotnet-feature-validator', suffix: 'Validator' },
 ];
 
-/** .NET feature-level files (entity, errors). */
 const DOTNET_FEATURE_TEMPLATES = [
   { templateId: 'dotnet-feature-entity', suffix: '', dir: 'entities' },
   { templateId: 'dotnet-feature-errors', suffix: 'Errors', dir: 'feature' },
 ];
 
-/**
- * Scaffold a .NET VSA feature slice.
- *
- * @param {Object} options
- * @param {string} options.feature - Entity/feature name in kebab-case (e.g., "book")
- * @param {string} options.sliceName - Slice name in kebab-case (e.g., "create-book")
- * @param {string} options.namespace - Root namespace (e.g., "MyApp")
- * @param {string} [options.outputDir] - Base output directory (default: cwd)
- * @param {boolean} [options.dryRun] - Preview without writing
- * @returns {{ files: Array<{path: string, content: string, skipped: boolean}> }}
- */
 export function scaffoldDotnetSlice(options) {
   const { feature, sliceName, namespace, outputDir = process.cwd(), dryRun = false } = options;
 
@@ -107,7 +61,6 @@ export function scaffoldDotnetSlice(options) {
 
   const files = [];
 
-  // 1. Render slice-level templates
   for (const tmpl of DOTNET_SLICE_TEMPLATES) {
     const templatePath = resolveFrameworkTemplatePath(tmpl.templateId);
     const outputPath = join(
@@ -128,7 +81,6 @@ export function scaffoldDotnetSlice(options) {
     files.push({ path: outputPath, content, skipped: false });
   }
 
-  // 2. Render feature-level templates (skip if already exist)
   for (const tmpl of DOTNET_FEATURE_TEMPLATES) {
     const templatePath = resolveFrameworkTemplatePath(tmpl.templateId);
     let outputPath;
@@ -157,12 +109,6 @@ export function scaffoldDotnetSlice(options) {
   return { files };
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Next.js Scaffold
-// ─────────────────────────────────────────────────────────────────────────────
-
-// Each entry pairs a REGISTRY.json template `id` with where the rendered file
-// lands. REGISTRY owns the template path; the generator owns the output path.
 const NEXTJS_TEMPLATES = [
   {
     templateId: 'nextjs-page',
@@ -182,15 +128,6 @@ const NEXTJS_TEMPLATES = [
   },
 ];
 
-/**
- * Scaffold a Next.js feature page with components and hooks.
- *
- * @param {Object} options
- * @param {string} options.featureName - Feature name in kebab-case (e.g., "book")
- * @param {string} [options.outputDir] - Base output directory (default: cwd)
- * @param {boolean} [options.dryRun] - Preview without writing
- * @returns {{ files: Array<{path: string, content: string, skipped: boolean}> }}
- */
 export function scaffoldNextjsFeature(options) {
   const { featureName, outputDir = process.cwd(), dryRun = false } = options;
 
@@ -226,33 +163,15 @@ export function scaffoldNextjsFeature(options) {
   return { files };
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Namespace Detection
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Detect the .NET root namespace from .csproj or config.json.
- *
- * Search order:
- * 1. *.csproj in dir (extract <RootNamespace>)
- * 2. *.csproj in dir (use filename without extension)
- * 3. *.csproj one level deep
- * 4. .morph/config.json → project.name
- *
- * @param {string} dir - Directory to search in
- * @returns {string|null} Detected namespace or null
- */
+/** <RootNamespace> or the name of a .csproj here or one level deep, else config.json `project.name`. */
 export function detectNamespace(dir) {
-  // 1. Search for .csproj in current dir
   const csprojInDir = findCsproj(dir);
   if (csprojInDir) {
     const ns = extractNamespaceFromCsproj(csprojInDir);
     if (ns) return ns;
-    // Fallback: use filename
     return basename(csprojInDir, '.csproj');
   }
 
-  // 2. Search one level deep
   try {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
@@ -265,29 +184,19 @@ export function detectNamespace(dir) {
         }
       }
     }
-  } catch {
-    // ignore read errors
-  }
+  } catch {}
 
-  // 3. Fall back to config.json
   const configPath = join(dir, '.morph', 'config.json');
   if (existsSync(configPath)) {
     try {
       const config = JSON.parse(readFileSync(configPath, 'utf-8'));
       if (config.project?.name) return config.project.name;
-    } catch {
-      // ignore parse errors
-    }
+    } catch {}
   }
 
   return null;
 }
 
-/**
- * Find the first .csproj file in a directory.
- * @param {string} dir
- * @returns {string|null}
- */
 function findCsproj(dir) {
   try {
     const entries = readdirSync(dir);
@@ -298,11 +207,6 @@ function findCsproj(dir) {
   }
 }
 
-/**
- * Extract <RootNamespace> from a .csproj file.
- * @param {string} csprojPath
- * @returns {string|null}
- */
 function extractNamespaceFromCsproj(csprojPath) {
   try {
     const content = readFileSync(csprojPath, 'utf-8');

package/src/lib/generators/settings-generator.js

@@ -1,10 +1,4 @@
-/**
- * Settings Generator
- *
- * Generates .claude/settings.local.json for projects based on detected
- * stack, MCPs, and morph-spec configuration. Uses _morph_managed marker
- * to track managed entries for safe reset.
- */
+// `_morph_managed` marks the managed entries, so a reset never touches the user's.
 
 import { join } from 'path';
 import { existsSync } from 'fs';
@@ -12,13 +6,6 @@ import { readFile, writeFile, mkdir } from 'fs/promises';
 
 const MORPH_MANAGED_KEY = '_morph_managed';
 
-/**
- * Generate and merge settings for a project
- * @param {string} targetPath - Project root directory
- * @param {Object} detectedConfig - Output from detectClaudeConfig()
- * @param {Object} morphConfig - morph-spec config (from .morph/config/config.json)
- * @returns {Promise<Object>} Generated settings summary
- */
 export async function generateSettings(targetPath, detectedConfig, morphConfig = {}) {
   const claudeDir = join(targetPath, '.claude');
   const settingsPath = join(claudeDir, 'settings.local.json');
@@ -32,11 +19,9 @@ export async function generateSettings(targetPath, detectedConfig, morphConfig =
     generated_at: new Date().toISOString()
   };
 
-  // Merge without overwriting user config
   const merged = mergeSettings(existing, generated);
   merged[MORPH_MANAGED_KEY] = managed;
 
-  // Ensure directory exists
   if (!existsSync(claudeDir)) {
     await mkdir(claudeDir, { recursive: true });
   }
@@ -49,12 +34,7 @@ export async function generateSettings(targetPath, detectedConfig, morphConfig =
   };
 }
 
-/**
- * Deep merge settings without overwriting user entries
- * @param {Object} existing - Current settings.local.json
- * @param {Object} generated - Generated settings to merge
- * @returns {Object} Merged settings
- */
+/** Never overwrites user entries: arrays are unioned, objects merged, only new keys added. */
 export function mergeSettings(existing, generated) {
   const result = { ...existing };
 
@@ -62,17 +42,14 @@ export function mergeSettings(existing, generated) {
     if (key === MORPH_MANAGED_KEY) continue;
 
     if (Array.isArray(value) && Array.isArray(result[key])) {
-      // Merge arrays without duplicates
       const set = new Set(result[key]);
       for (const item of value) {
         set.add(item);
       }
       result[key] = [...set];
     } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-      // Recursively merge objects
       result[key] = mergeSettings(result[key] || {}, value);
     } else if (!(key in result)) {
-      // Only add new keys, never overwrite existing
       result[key] = value;
     }
   }
@@ -80,11 +57,6 @@ export function mergeSettings(existing, generated) {
   return result;
 }
 
-/**
- * Save integrations.json with detected config
- * @param {string} targetPath - Project root directory
- * @param {Object} detectedConfig - Output from detectClaudeConfig()
- */
 export async function saveIntegrations(targetPath, detectedConfig) {
   const integrationsPath = join(targetPath, '.morph', 'config', 'integrations.json');
   const integrationsDir = join(targetPath, '.morph', 'config');
@@ -107,13 +79,8 @@ export async function saveIntegrations(targetPath, detectedConfig) {
   return integrationsPath;
 }
 
-// ============================================================================
-// Helpers
-// ============================================================================
-
-// Claude Code reads only `permissions: { allow, deny }`; a bare array (older generator) is ignored.
-// Versões antigas gravavam regras curinga (node:*, npm:*, npx:*…) como array, forma que o
-// Claude Code ignora: nunca valeram. Converter para { allow } as ligaria em silêncio.
+// Claude Code reads only `permissions: { allow, deny }`. Old generators wrote wildcard rules as a bare
+// array that never applied; converting it to { allow } would silently enable them.
 function withoutLegacyPermissions(settings) {
   if (!Array.isArray(settings.permissions)) return settings;
   const { permissions, ...rest } = settings;

package/src/lib/git/branch-classifier.js

@@ -1,36 +1,6 @@
-/**
- * branch-classifier.js — answer "is this branch's work already in the default
- * branch?" for a repository that squash-merges.
- *
- * WHY THIS EXISTS: a squash-merge puts the WORK in `origin/master` while
- * leaving none of the branch's own commits reachable from it. So
- * `git branch --merged origin/master` does not list the branch, and
- * `git branch -d` refuses it as unmerged. The only remaining command is
- * `git branch -D`, which is byte-identical to the command that discards real,
- * never-integrated work — the tool gives the user no way to tell the two apart,
- * and after enough of these the habit becomes "just -D it", which is how work
- * gets lost.
- *
- * Every branch lands in exactly one class, and only the two MERGED ones are
- * ever deletable:
- *
- *   merged-ancestral — git itself proves it: the branch tip is an ancestor of
- *                      the default. A plain merge, or a fast-forward.
- *   merged-squash    — git cannot see it, but the evidence is positive: either
- *                      GitHub reports the PR as MERGED, or the branch's tree is
- *                      IDENTICAL to the default's (every change it carries is
- *                      already there under a different commit).
- *   open             — a PR is OPEN for it. Never deleted: the PR is the whole
- *                      reason the branch must survive.
- *   in-worktree      — checked out by a live worktree. Never deleted.
- *   unmerged         — none of the above could be PROVEN. This is the fail-safe
- *                      default and covers "no `gh`", "no origin", and "genuinely
- *                      unintegrated work" alike, because from here they are the
- *                      same thing: not proven integrated.
- *
- * Nothing here mutates. `pruneBranches` in commands/project/branch.js does the
- * deleting, and it deletes ONLY what this file classified as merged.
- */
+// A squash-merge leaves the work in the default branch but none of the branch's commits,
+// so `branch -d` refuses it and `-D` looks like discarding real work. Only the two
+// `merged-*` classes are deletable; anything not PROVEN integrated is `unmerged`.
 
 import { execFileSync } from 'child_process';
 
@@ -38,11 +8,7 @@ function git(args, cwd) {
   return execFileSync('git', args, { cwd, stdio: 'pipe' }).toString();
 }
 
-/**
- * Local branches with their tips. Excludes nothing — the caller decides.
- *
- * @returns {Array<{ name: string, sha: string, current: boolean, worktreePath: string|null }>}
- */
+/** @returns {Array<{ name: string, sha: string, current: boolean, worktreePath: string|null }>} */
 export function listLocalBranches(cwd) {
   try {
     const out = git(['for-each-ref', '--format=%(refname:short)%09%(objectname)%09%(HEAD)%09%(worktreepath)', 'refs/heads/'], cwd);
@@ -55,7 +21,6 @@ export function listLocalBranches(cwd) {
   }
 }
 
-/** Is `ancestor` reachable from `descendant`? False on any git error. */
 function isAncestor(ancestor, descendant, cwd) {
   try {
     git(['merge-base', '--is-ancestor', ancestor, descendant], cwd);
@@ -65,19 +30,8 @@ function isAncestor(ancestor, descendant, cwd) {
   }
 }
 
-/**
- * Does the branch introduce NOTHING the base does not already have?
- *
- * `git diff --quiet <base> <branch>` compares the two TREES: an empty diff
- * means every file the branch touched already reads exactly as the branch left
- * it in the base. That is precisely the state a squash-merge produces, and it
- * is a positive proof rather than an inference from history shape.
- *
- * Deliberately NOT `base...branch` (the three-dot form diffs against the merge
- * base, which for a squash-merged branch still shows the branch's own changes).
- *
- * Fail-CLOSED: any git error reads as "introduces something", never as merged.
- */
+// Two-dot tree diff, never `base...branch`: the three-dot form still shows a squash-merged
+// branch's own changes. Fail-closed: a git error never reads as merged.
 function treeIsIdentical(base, branch, cwd) {
   try {
     execFileSync('git', ['diff', '--quiet', base, branch], { cwd, stdio: 'pipe' });
@@ -87,13 +41,7 @@ function treeIsIdentical(base, branch, cwd) {
   }
 }
 
-/**
- * How many commits the branch carries that the base does not. Used only for
- * REPORTING — the classification never turns on it, because a squash-merged
- * branch legitimately has commits ahead while carrying no unintegrated work.
- *
- * @returns {number|null} null when it cannot be computed
- */
+/** Reporting only: a squash-merged branch legitimately has commits ahead. @returns {number|null} */
 export function commitsAhead(base, branch, cwd) {
   try {
     const out = git(['rev-list', '--count', `${base}..${branch}`], cwd).trim();
@@ -105,12 +53,8 @@ export function commitsAhead(base, branch, cwd) {
 }
 
 /**
- * Resolve the ref to compare against: `origin/<default>` when the remote-tracking
- * ref exists (the authority on what has actually landed), else the local branch.
- *
- * @returns {string|null} null when neither resolves — the caller must then
- *   classify everything as `unmerged`, because there is no baseline to prove
- *   integration against.
+ * `origin/<default>` when it exists, else the local branch.
+ * @returns {string|null} null = no baseline, so everything is `unmerged`.
  */
 export function resolveBaseRef(defaultBranch, cwd) {
   if (!defaultBranch) return null;
@@ -123,19 +67,8 @@ export function resolveBaseRef(defaultBranch, cwd) {
   return null;
 }
 
-/**
- * Classify one branch. Pure decision logic over already-gathered facts, so the
- * table above is testable without a GitHub account.
- *
- * ORDER IS THE POLICY, and the two protective classes come FIRST: a branch that
- * is checked out, or that carries an OPEN PR, is never deleted even if its tree
- * happens to match the base — a PR being open means a human still has business
- * with it.
- *
- * @param {object} b - from listLocalBranches
- * @param {{ baseRef: string|null, cwd: string, pr: {number:number,state:string}|null|undefined }} ctx
- * @returns {{ name: string, kind: string, reason: string, pr: number|null, ahead: number|null, deletable: boolean }}
- */
+// Order is the policy: checked-out and open-PR branches are protected before any
+// merged check, even when the tree matches the base.
 export function classifyBranch(b, { baseRef, cwd, pr }) {
   const prNum = pr?.number ?? null;
   const mk = (kind, reason, deletable) => ({
@@ -163,12 +96,6 @@ export function classifyBranch(b, { baseRef, cwd, pr }) {
   return mk('unmerged', `carrega mudanças que não estão em ${baseRef} e nenhum PR MERGED comprova o contrário`, false);
 }
 
-/**
- * Classify every local branch except the default itself.
- *
- * @param {{ cwd: string, defaultBranch: string|null, prIndex: Map|null }} ctx
- * @returns {Array} one entry per branch, in `for-each-ref` order
- */
 export function classifyBranches({ cwd, defaultBranch, prIndex }) {
   const baseRef = resolveBaseRef(defaultBranch, cwd);
   return listLocalBranches(cwd)