@polymorphism-tech/morph-spec 4.8.1 → 4.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/README.md +2 -2
  2. package/claude-plugin.json +1 -1
  3. package/docs/CHEATSHEET.md +1 -1
  4. package/docs/QUICKSTART.md +1 -1
  5. package/framework/hooks/dev/guard-version-numbers.js +1 -1
  6. package/framework/skills/level-1-workflows/phase-clarify/SKILL.md +1 -1
  7. package/framework/skills/level-1-workflows/phase-codebase-analysis/SKILL.md +1 -1
  8. package/framework/skills/level-1-workflows/phase-design/SKILL.md +1 -1
  9. package/framework/skills/level-1-workflows/phase-implement/SKILL.md +1 -1
  10. package/framework/skills/level-1-workflows/phase-setup/SKILL.md +1 -1
  11. package/framework/skills/level-1-workflows/phase-tasks/SKILL.md +1 -1
  12. package/framework/skills/level-1-workflows/phase-uiux/SKILL.md +1 -1
  13. package/package.json +4 -4
  14. package/.morph/analytics/threads-log.jsonl +0 -54
  15. package/.morph/state.json +0 -198
  16. package/docs/ARCHITECTURE.md +0 -328
  17. package/docs/COMMAND-FLOWS.md +0 -398
  18. package/docs/plans/2026-02-22-claude-docs-morph-alignment-analysis.md +0 -514
  19. package/docs/plans/2026-02-22-claude-settings.md +0 -517
  20. package/docs/plans/2026-02-22-morph-cc-alignment-impl.md +0 -730
  21. package/docs/plans/2026-02-22-morph-spec-next.md +0 -480
  22. package/docs/plans/2026-02-22-native-alignment-design.md +0 -201
  23. package/docs/plans/2026-02-22-native-alignment-impl.md +0 -927
  24. package/docs/plans/2026-02-22-native-enrichment-design.md +0 -246
  25. package/docs/plans/2026-02-22-native-enrichment.md +0 -737
  26. package/docs/plans/2026-02-23-ddd-architecture-refactor.md +0 -1155
  27. package/docs/plans/2026-02-23-ddd-nextsteps.md +0 -684
  28. package/docs/plans/2026-02-23-infra-architect-refactor.md +0 -439
  29. package/docs/plans/2026-02-23-nextjs-code-review-design.md +0 -157
  30. package/docs/plans/2026-02-23-nextjs-code-review-impl.md +0 -1256
  31. package/docs/plans/2026-02-23-nextjs-standards-design.md +0 -150
  32. package/docs/plans/2026-02-23-nextjs-standards-impl.md +0 -1848
  33. package/docs/plans/2026-02-24-cli-radical-simplification.md +0 -592
  34. package/docs/plans/2026-02-24-framework-failure-points.md +0 -125
  35. package/docs/plans/2026-02-24-morph-init-design.md +0 -337
  36. package/docs/plans/2026-02-24-morph-init-impl.md +0 -1269
  37. package/docs/plans/2026-02-24-tutorial-command-design.md +0 -71
  38. package/docs/plans/2026-02-24-tutorial-command.md +0 -298
  39. package/scripts/bump-version.js +0 -248
  40. package/scripts/generate-refs.js +0 -336
  41. package/scripts/generate-standards-registry.js +0 -44
  42. package/scripts/install-dev-hooks.js +0 -138
  43. package/scripts/scan-nextjs.mjs +0 -169
  44. package/scripts/validate-real.mjs +0 -255
@@ -1,336 +0,0 @@
1
- #!/usr/bin/env node
2
- /**
3
- * scripts/generate-refs.js
4
- *
5
- * Generates derived files from the single source of truth:
6
- * src/core/paths/output-schema.js
7
- *
8
- * Outputs:
9
- * framework/hooks/shared/phase-utils.js — constants derived from OUTPUT_SCHEMA
10
- * framework/skills/level-1-workflows/*.md — morph:outputs blocks
11
- *
12
- * Usage:
13
- * node scripts/generate-refs.js # generate files
14
- * node scripts/generate-refs.js --check # validate only (CI, exit 1 if drift)
15
- */
16
-
17
- import { readFileSync, writeFileSync, existsSync } from 'fs';
18
- import { join, dirname } from 'path';
19
- import { fileURLToPath } from 'url';
20
- import { OUTPUT_SCHEMA } from '../src/core/paths/output-schema.js';
21
-
22
- const __dirname = dirname(fileURLToPath(import.meta.url));
23
- const ROOT = join(__dirname, '..');
24
- const CHECK_MODE = process.argv.includes('--check');
25
-
26
- // ============================================================================
27
- // Configuration
28
- // ============================================================================
29
-
30
- /**
31
- * Phase entries that cannot be derived from OUTPUT_SCHEMA because they share
32
- * directories with other phases (no dedicated output type of their own).
33
- */
34
- const PHASE_DIRS_EXTRAS = {
35
- setup: '0-proposal', // setup outputs (proposal.md) go in 0-proposal dir
36
- sync: '4-implement', // sync updates standards, works in implement space
37
- };
38
-
39
- /** Canonical phase ordering for PHASE_ORDER constant. */
40
- const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'tasks', 'implement', 'sync'];
41
-
42
- /**
43
- * Skill files that contain <!-- morph:outputs:PHASE --> blocks.
44
- * Keyed by the phase name to inject, value is the file path relative to ROOT.
45
- */
46
- const SKILL_FILES = [
47
- { file: 'framework/skills/level-1-workflows/phase-setup.md', phase: 'proposal' },
48
- { file: 'framework/skills/level-1-workflows/phase-uiux.md', phase: 'uiux' },
49
- { file: 'framework/skills/level-1-workflows/phase-design.md', phase: 'design' },
50
- { file: 'framework/skills/level-1-workflows/phase-tasks.md', phase: 'tasks' },
51
- { file: 'framework/skills/level-1-workflows/phase-implement.md', phase: 'implement' },
52
- ];
53
-
54
- // ============================================================================
55
- // Derivation helpers
56
- // ============================================================================
57
-
58
- function derivePhaseDirs() {
59
- const dirs = {};
60
- for (const entry of Object.values(OUTPUT_SCHEMA)) {
61
- dirs[entry.phase] = entry.phaseDir;
62
- }
63
- // Add extras in their canonical order (will be merged after schema-derived entries)
64
- for (const [phase, dir] of Object.entries(PHASE_DIRS_EXTRAS)) {
65
- dirs[phase] = dir;
66
- }
67
- // Re-order to match PHASE_ORDER
68
- const ordered = {};
69
- for (const phase of PHASE_ORDER) {
70
- if (dirs[phase]) ordered[phase] = dirs[phase];
71
- }
72
- return ordered;
73
- }
74
-
75
- function deriveOutputPhaseMap() {
76
- return Object.fromEntries(
77
- Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [key, entry.phase])
78
- );
79
- }
80
-
81
- function deriveFilenameToOutput() {
82
- return Object.fromEntries(
83
- Object.entries(OUTPUT_SCHEMA).map(([key, entry]) => [entry.filename, key])
84
- );
85
- }
86
-
87
- function deriveProtectedSpecFiles() {
88
- return Object.fromEntries(
89
- Object.entries(OUTPUT_SCHEMA)
90
- .filter(([, entry]) => entry.protected && entry.approvalGate)
91
- .map(([, entry]) => [entry.filename, entry.approvalGate])
92
- );
93
- }
94
-
95
- // ============================================================================
96
- // phase-utils.js generator
97
- // ============================================================================
98
-
99
- /**
100
- * Static utility functions that live in phase-utils.js.
101
- * Not derived from OUTPUT_SCHEMA — they operate on file paths generically.
102
- */
103
- const UTIL_FUNCTIONS = `
104
- /**
105
- * Extract feature name from a .morph/features/{feature}/... path
106
- * @param {string} filePath - File path to analyze
107
- * @returns {string|null} Feature name or null
108
- */
109
- export function extractFeatureName(filePath) {
110
- const normalized = filePath.replace(/\\\\/g, '/');
111
- const match = normalized.match(/\\.morph\\/features\\/([^/]+)\\//);
112
- return match ? match[1] : null;
113
- }
114
-
115
- /**
116
- * Extract phase subdirectory from a .morph/features/{feature}/{phaseDir}/... path
117
- * @param {string} filePath - File path to analyze
118
- * @returns {string|null} Phase directory (e.g., '0-proposal', '1-design') or null
119
- */
120
- export function extractPhaseDir(filePath) {
121
- const normalized = filePath.replace(/\\\\/g, '/');
122
- const match = normalized.match(/\\.morph\\/features\\/[^/]+\\/(\\d+-[^/]+)\\//);
123
- return match ? match[1] : null;
124
- }
125
-
126
- /**
127
- * Check if a file path is inside .morph/features/
128
- * @param {string} filePath
129
- * @returns {boolean}
130
- */
131
- export function isFeaturePath(filePath) {
132
- const normalized = filePath.replace(/\\\\/g, '/');
133
- return normalized.includes('.morph/features/');
134
- }
135
-
136
- /**
137
- * Check if a file path is inside .morph/framework/ (readonly)
138
- * @param {string} filePath
139
- * @returns {boolean}
140
- */
141
- export function isFrameworkPath(filePath) {
142
- const normalized = filePath.replace(/\\\\/g, '/');
143
- return normalized.includes('.morph/framework/');
144
- }
145
-
146
- /**
147
- * Check if a file path is state.json
148
- * @param {string} filePath
149
- * @returns {boolean}
150
- */
151
- export function isStatePath(filePath) {
152
- const normalized = filePath.replace(/\\\\/g, '/');
153
- return normalized.endsWith('.morph/state.json');
154
- }
155
-
156
- /**
157
- * Get the basename of a file path
158
- * @param {string} filePath
159
- * @returns {string}
160
- */
161
- export function getBasename(filePath) {
162
- const normalized = filePath.replace(/\\\\/g, '/');
163
- return normalized.split('/').pop();
164
- }
165
- `;
166
-
167
- function formatJsObject(obj) {
168
- const needsQuotes = (key) => /[^a-zA-Z0-9_$]/.test(key);
169
- const entries = Object.entries(obj).map(([k, v]) => {
170
- const fmtKey = needsQuotes(k) ? `'${k}'` : k;
171
- return ` ${fmtKey}: '${v}',`;
172
- });
173
- return `{\n${entries.join('\n')}\n}`;
174
- }
175
-
176
- function generatePhaseUtilsContent() {
177
- const phaseDirs = derivePhaseDirs();
178
- const outputPhaseMap = deriveOutputPhaseMap();
179
- const filenameToOut = deriveFilenameToOutput();
180
- const protectedFiles = deriveProtectedSpecFiles();
181
-
182
- return `// GENERATED by scripts/generate-refs.js — DO NOT EDIT manually
183
- // Source of truth: src/core/paths/output-schema.js
184
- // Regenerate with: node scripts/generate-refs.js
185
- /**
186
- * Shared phase utilities for Claude Code hooks.
187
- *
188
- * Maps phases to directories and output types.
189
- */
190
-
191
- /** Phase order */
192
- export const PHASE_ORDER = ${JSON.stringify(PHASE_ORDER)};
193
-
194
- /** Map phase → allowed output subdirectory */
195
- export const PHASE_DIRS = ${formatJsObject(phaseDirs)};
196
-
197
- /** Map output type (camelCase) → phase that produces it */
198
- export const OUTPUT_PHASE_MAP = ${formatJsObject(outputPhaseMap)};
199
-
200
- /** Map filename → output type (camelCase) */
201
- export const FILENAME_TO_OUTPUT = ${formatJsObject(filenameToOut)};
202
-
203
- /** Protected spec files and the approval gate that locks them */
204
- export const PROTECTED_SPEC_FILES = ${formatJsObject(protectedFiles)};
205
- ${UTIL_FUNCTIONS}`;
206
- }
207
-
208
- // ============================================================================
209
- // Markdown block generator
210
- // ============================================================================
211
-
212
- function generateOutputTable(phaseName) {
213
- const entries = Object.entries(OUTPUT_SCHEMA)
214
- .filter(([, entry]) => entry.phase === phaseName);
215
-
216
- if (entries.length === 0) return null;
217
-
218
- const rows = entries
219
- .map(([key, entry]) =>
220
- `| \`${key}\` | \`.morph/features/{feature}/${entry.phaseDir}/${entry.filename}\` |`
221
- )
222
- .join('\n');
223
-
224
- return `| Output | Caminho |\n|--------|---------|
225
- ${rows}`;
226
- }
227
-
228
- function replaceMarkdownBlocks(content, phaseName) {
229
- const table = generateOutputTable(phaseName);
230
- if (!table) return { changed: false, content };
231
-
232
- const updated = content.replace(
233
- /<!-- morph:outputs:(\w+) -->([\s\S]*?)<!-- \/morph:outputs -->/g,
234
- (_match, blockPhase, _inner) => {
235
- const blockTable = generateOutputTable(blockPhase);
236
- if (!blockTable) return _match;
237
- return `<!-- morph:outputs:${blockPhase} -->\n${blockTable}\n<!-- /morph:outputs -->`;
238
- }
239
- );
240
-
241
- return { changed: updated !== content, content: updated };
242
- }
243
-
244
- // ============================================================================
245
- // Write / check helpers
246
- // ============================================================================
247
-
248
- let driftFound = false;
249
-
250
- function writeOrCheck(filePath, generated, label) {
251
- const current = existsSync(filePath) ? readFileSync(filePath, 'utf8') : null;
252
-
253
- if (current === generated) {
254
- console.log(` ✓ ${label} — up to date`);
255
- return;
256
- }
257
-
258
- if (CHECK_MODE) {
259
- console.error(` ✗ ${label} — DRIFT DETECTED (run: node scripts/generate-refs.js)`);
260
- if (current === null) {
261
- console.error(` File does not exist: ${filePath}`);
262
- } else {
263
- // Show first difference line
264
- const curLines = current.split('\n');
265
- const genLines = generated.split('\n');
266
- for (let i = 0; i < Math.max(curLines.length, genLines.length); i++) {
267
- if (curLines[i] !== genLines[i]) {
268
- console.error(` First diff at line ${i + 1}:`);
269
- console.error(` current: ${JSON.stringify(curLines[i] ?? '(missing)')}`);
270
- console.error(` generated: ${JSON.stringify(genLines[i] ?? '(missing)')}`);
271
- break;
272
- }
273
- }
274
- }
275
- driftFound = true;
276
- } else {
277
- writeFileSync(filePath, generated, 'utf8');
278
- console.log(` ✎ ${label} — updated`);
279
- }
280
- }
281
-
282
- // ============================================================================
283
- // Main
284
- // ============================================================================
285
-
286
- console.log(CHECK_MODE ? '\nChecking generated refs...' : '\nGenerating refs from output-schema.js...');
287
- console.log('');
288
-
289
- // 1. Generate / check phase-utils.js
290
- const phaseUtilsPath = join(ROOT, 'framework/hooks/shared/phase-utils.js');
291
- const phaseUtilsContent = generatePhaseUtilsContent();
292
- writeOrCheck(phaseUtilsPath, phaseUtilsContent, 'framework/hooks/shared/phase-utils.js');
293
-
294
- // 2. Update / check morph:outputs blocks in skill markdown files
295
- console.log('');
296
- for (const { file, phase } of SKILL_FILES) {
297
- const filePath = join(ROOT, file);
298
- if (!existsSync(filePath)) {
299
- console.log(` - ${file} — not found, skipping`);
300
- continue;
301
- }
302
-
303
- const content = readFileSync(filePath, 'utf8');
304
- const hasMarker = content.includes(`<!-- morph:outputs:${phase} -->`);
305
-
306
- if (!hasMarker) {
307
- console.log(` - ${file} — no morph:outputs:${phase} marker, skipping`);
308
- continue;
309
- }
310
-
311
- const { changed, content: updated } = replaceMarkdownBlocks(content, phase);
312
-
313
- if (!changed) {
314
- console.log(` ✓ ${file} — up to date`);
315
- } else if (CHECK_MODE) {
316
- console.error(` ✗ ${file} — morph:outputs block DRIFT DETECTED`);
317
- driftFound = true;
318
- } else {
319
- writeFileSync(filePath, updated, 'utf8');
320
- console.log(` ✎ ${file} — morph:outputs block updated`);
321
- }
322
- }
323
-
324
- console.log('');
325
-
326
- if (CHECK_MODE) {
327
- if (driftFound) {
328
- console.error('FAIL: Generated files are out of sync with output-schema.js');
329
- console.error(' Run: node scripts/generate-refs.js');
330
- process.exit(1);
331
- } else {
332
- console.log('OK: All generated refs are in sync with output-schema.js');
333
- }
334
- } else {
335
- console.log('Done. Commit any changed files.');
336
- }
@@ -1,44 +0,0 @@
1
- #!/usr/bin/env node
2
- /**
3
- * One-time script to generate framework/standards/STANDARDS.json
4
- * by scanning all .md files in framework/standards/.
5
- *
6
- * Usage: node scripts/generate-standards-registry.js
7
- */
8
-
9
- import { readdirSync, statSync, writeFileSync } from 'fs';
10
- import { join, relative } from 'path';
11
- import { fileURLToPath } from 'url';
12
-
13
- const __dirname = fileURLToPath(new URL('.', import.meta.url));
14
- const BASE = join(__dirname, '..', 'framework', 'standards');
15
-
16
- function scanDir(dir) {
17
- const entries = [];
18
- for (const f of readdirSync(dir)) {
19
- const full = join(dir, f);
20
- const rel = relative(BASE, full).replace(/\\/g, '/');
21
- if (statSync(full).isDirectory()) {
22
- entries.push(...scanDir(full));
23
- } else if (f.endsWith('.md') && f !== 'README.md') {
24
- const parts = rel.split('/');
25
- entries.push({
26
- id: rel.replace(/\//g, '-').replace('.md', ''),
27
- name: f.replace('.md', '').replace(/-/g, ' '),
28
- path: rel,
29
- category: parts[0],
30
- subcategory: parts.length > 2 ? parts[1] : null,
31
- tags: parts.slice(0, -1),
32
- });
33
- }
34
- }
35
- return entries;
36
- }
37
-
38
- const standards = scanDir(BASE);
39
- const registry = { version: '1.0.0', standards };
40
- const outPath = join(BASE, 'STANDARDS.json');
41
- writeFileSync(outPath, JSON.stringify(registry, null, 2) + '\n');
42
- console.log(`Generated ${standards.length} standards entries`);
43
- console.log(`Categories: ${[...new Set(standards.map(s => s.category))].join(', ')}`);
44
- console.log(`Written to: ${outPath}`);
@@ -1,138 +0,0 @@
1
- #!/usr/bin/env node
2
-
3
- /**
4
- * Dev Hooks Installer for MORPH-SPEC Framework Codebase
5
- *
6
- * Installs development-only hooks into .claude/settings.local.json.
7
- * These hooks enforce quality standards when developing the framework itself:
8
- * - Version number guard (no hardcoded versions in .md files)
9
- * - Standard format validator (required metadata headers)
10
- * - Skill frontmatter validator (required YAML fields)
11
- * - Template registry sync advisory
12
- * - Standards registry sync advisory
13
- * - Sync health check advisory on Stop
14
- *
15
- * Usage: node scripts/install-dev-hooks.js
16
- *
17
- * Dev hooks use _morph_dev:true marker (not _morph:true) so they survive
18
- * `morph-spec init/update` reinstalls, which only remove _morph:true entries.
19
- */
20
-
21
- import { readFile, writeFile, mkdir } from 'fs/promises';
22
- import { existsSync } from 'fs';
23
- import { join } from 'path';
24
-
25
- /**
26
- * Dev hook definitions.
27
- * Commands reference framework/hooks/dev/ directly (not .morph/framework/)
28
- * since they only run in the framework repo where this path exists.
29
- */
30
- const DEV_HOOKS = [
31
- {
32
- event: 'PreToolUse',
33
- matcher: 'Write|Edit',
34
- hooks: [
35
- { type: 'command', command: 'node framework/hooks/dev/guard-version-numbers.js' },
36
- { type: 'command', command: 'node framework/hooks/dev/validate-standard-format.js' },
37
- { type: 'command', command: 'node framework/hooks/dev/validate-skill-format.js' },
38
- ]
39
- },
40
- {
41
- event: 'PostToolUse',
42
- matcher: 'Write',
43
- hooks: [
44
- { type: 'command', command: 'node framework/hooks/dev/sync-template-registry.js' },
45
- { type: 'command', command: 'node framework/hooks/dev/sync-standards-registry.js' },
46
- ]
47
- },
48
- {
49
- event: 'Stop',
50
- matcher: null,
51
- hooks: [
52
- { type: 'command', command: 'node framework/hooks/dev/check-sync-health.js' },
53
- ]
54
- },
55
- ];
56
-
57
- /**
58
- * Install dev hooks into .claude/settings.local.json.
59
- * Preserves _morph:true entries and user hooks.
60
- * Removes old _morph_dev:true entries before installing (clean slate).
61
- *
62
- * @param {string} [projectPath] - Project root (defaults to cwd)
63
- * @returns {Promise<{ installed: number }>}
64
- */
65
- export async function installDevHooks(projectPath) {
66
- const root = projectPath || process.cwd();
67
- const claudeDir = join(root, '.claude');
68
- const settingsPath = join(claudeDir, 'settings.local.json');
69
-
70
- // Read existing settings
71
- let settings = {};
72
- if (existsSync(settingsPath)) {
73
- try {
74
- settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
75
- } catch {
76
- settings = {};
77
- }
78
- }
79
-
80
- settings.hooks = settings.hooks || {};
81
-
82
- // Remove old dev hooks (clean slate)
83
- for (const [event, entries] of Object.entries(settings.hooks)) {
84
- if (!Array.isArray(entries)) continue;
85
- settings.hooks[event] = entries.filter(entry => entry._morph_dev !== true);
86
- if (settings.hooks[event].length === 0) {
87
- delete settings.hooks[event];
88
- }
89
- }
90
-
91
- // Install dev hooks
92
- let installed = 0;
93
- for (const hookDef of DEV_HOOKS) {
94
- const { event, matcher, hooks } = hookDef;
95
-
96
- if (!settings.hooks[event]) {
97
- settings.hooks[event] = [];
98
- }
99
-
100
- const entry = { _morph_dev: true };
101
- if (matcher) {
102
- entry.matcher = matcher;
103
- }
104
- entry.hooks = hooks.map(h => ({ type: h.type, command: h.command }));
105
-
106
- settings.hooks[event].push(entry);
107
- installed++;
108
- }
109
-
110
- // Ensure .claude directory exists
111
- if (!existsSync(claudeDir)) {
112
- await mkdir(claudeDir, { recursive: true });
113
- }
114
-
115
- await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
116
- return { installed };
117
- }
118
-
119
- /**
120
- * Get the dev hooks definitions (for testing/inspection).
121
- * @returns {Array}
122
- */
123
- export function getDevHookDefinitions() {
124
- return DEV_HOOKS;
125
- }
126
-
127
- // CLI entry point
128
- const isMainModule = process.argv[1]?.replace(/\\/g, '/').endsWith('scripts/install-dev-hooks.js');
129
- if (isMainModule) {
130
- try {
131
- const result = await installDevHooks();
132
- console.log(`Installed ${result.installed} dev hooks into .claude/settings.local.json`);
133
- console.log('Dev hooks are active for framework development only (_morph_dev: true).');
134
- } catch (err) {
135
- console.error('Failed to install dev hooks:', err.message);
136
- process.exit(1);
137
- }
138
- }
@@ -1,169 +0,0 @@
1
- #!/usr/bin/env node
2
- /**
3
- * scan-nextjs.mjs - CLI scan for Next.js violations.
4
- * Usage: node scripts/scan-nextjs.mjs [path] [--json]
5
- * Exit: 0=clean, 1=errors, 2=scan failed
6
- */
7
-
8
- import { readFileSync, existsSync, readdirSync } from 'node:fs';
9
- import { join, resolve } from 'node:path';
10
- import { validateNextComponent } from '../src/lib/validators/nextjs/next-component-validator.js';
11
-
12
- const args = process.argv.slice(2);
13
- const jsonMode = args.includes('--json');
14
- const pathArg = args.find(a => !a.startsWith('--'));
15
- const targetPath = pathArg ? resolve(pathArg) : resolve('src');
16
-
17
- function checkUseEffectFetch(content, filePath) {
18
- const issues = [];
19
- if (/useEffect\s*\(\s*(?:async\s+)?\(\s*\)\s*=>/.test(content) && /\bfetch\s*\(/.test(content)) {
20
- issues.push({
21
- type: 'error',
22
- message: "useEffect used for data fetching — use Server Components or TanStack Query (useQuery) instead",
23
- suggestion: "Replace with a Server Component fetch or TanStack Query useQuery hook",
24
- file: filePath,
25
- });
26
- }
27
- return issues;
28
- }
29
-
30
- function checkDefaultExport(content, filePath) {
31
- const issues = [];
32
- const fileName = filePath.split('/').pop() ?? '';
33
- const SPECIAL = ['page.tsx', 'layout.tsx', 'loading.tsx', 'error.tsx', 'not-found.tsx'];
34
- if (!SPECIAL.includes(fileName) && /^export\s+default\s+/m.test(content) && fileName.endsWith('.tsx')) {
35
- issues.push({
36
- type: 'warning',
37
- message: `Default export in '${fileName}' — prefer named exports for easier refactoring`,
38
- suggestion: "Change to: export function ComponentName() {}",
39
- file: filePath,
40
- });
41
- }
42
- return issues;
43
- }
44
-
45
- function findTsxFiles(dir) {
46
- const results = [];
47
- let entries;
48
- try {
49
- entries = readdirSync(dir, { withFileTypes: true });
50
- } catch {
51
- return results;
52
- }
53
- for (const entry of entries) {
54
- const fullPath = join(dir, entry.name);
55
- if (['node_modules', '.next', 'dist', '.git'].includes(entry.name)) continue;
56
- if (entry.isDirectory()) {
57
- results.push(...findTsxFiles(fullPath));
58
- } else if (entry.name.endsWith('.tsx') || entry.name.endsWith('.ts')) {
59
- results.push(fullPath);
60
- }
61
- }
62
- return results;
63
- }
64
- function main() {
65
- if (!existsSync(targetPath)) {
66
- const msg = `Error: Path does not exist: ${targetPath}`;
67
- if (jsonMode) {
68
- console.log(JSON.stringify({ error: msg, exitCode: 2 }));
69
- } else {
70
- process.stderr.write(msg + '\n');
71
- }
72
- process.exit(2);
73
- }
74
-
75
- let files;
76
- try {
77
- files = findTsxFiles(targetPath);
78
- } catch (err) {
79
- const msg = `Error scanning directory: ${err.message}`;
80
- if (jsonMode) {
81
- console.log(JSON.stringify({ error: msg, exitCode: 2 }));
82
- } else {
83
- process.stderr.write(msg + '\n');
84
- }
85
- process.exit(2);
86
- }
87
-
88
- const normalizedTarget = targetPath.replace(/\\/g, '/');
89
-
90
- const allIssues = [];
91
- for (const filePath of files) {
92
- let content;
93
- try {
94
- content = readFileSync(filePath, 'utf8');
95
- } catch {
96
- continue;
97
- }
98
- const normalizedFile = filePath.replace(/\\/g, '/');
99
- const relPath = normalizedFile.startsWith(normalizedTarget)
100
- ? normalizedFile.slice(normalizedTarget.length).replace(/^\//, '')
101
- : normalizedFile;
102
-
103
- const issues = [
104
- ...validateNextComponent(content, relPath),
105
- ...checkUseEffectFetch(content, relPath),
106
- ...checkDefaultExport(content, relPath),
107
- ];
108
- allIssues.push(...issues);
109
- }
110
-
111
- const errors = allIssues.filter(i => i.type === 'error');
112
- const warnings = allIssues.filter(i => i.type === 'warning');
113
-
114
- if (jsonMode) {
115
- const out = JSON.stringify({
116
- files: files.length,
117
- issues: allIssues.map(i => ({
118
- severity: i.type,
119
- message: i.message,
120
- file: i.file,
121
- line: i.line ?? null,
122
- suggestion: i.suggestion ?? null,
123
- })),
124
- errors: errors.length,
125
- warnings: warnings.length,
126
- exitCode: errors.length > 0 ? 1 : 0,
127
- }, null, 2);
128
- process.stdout.write(out + '\n');
129
- process.exit(errors.length > 0 ? 1 : 0);
130
- }
131
-
132
- const displayPath = targetPath.replace(process.cwd().replace(/\\/g, '/'), '.').replace(/\\/g, '/');
133
- console.log(`🔍 Scanning ${displayPath} (${files.length} file${files.length !== 1 ? "s" : ""})...`);
134
- console.log("");
135
-
136
- if (allIssues.length === 0) {
137
- console.log(`✅ No issues found — ${files.length} file${files.length !== 1 ? "s" : ""} scanned`);
138
- console.log(`Summary: ${files.length} files scanned | 0 issues (0 critical, 0 high, 0 medium)`);
139
- process.exit(0);
140
- }
141
-
142
- if (errors.length > 0) {
143
- console.log(`CRITICAL (${errors.length})`);
144
- for (const issue of errors) {
145
- const loc = issue.line ? `:${issue.line}` : "";
146
- console.log(` ${issue.file}${loc} — ${issue.message}`);
147
- if (issue.suggestion) console.log(` → ${issue.suggestion}`);
148
- }
149
- console.log('');
150
- }
151
-
152
- if (warnings.length > 0) {
153
- console.log(`HIGH/MEDIUM (${warnings.length})`);
154
- for (const issue of warnings) {
155
- console.log(` ${issue.file} — ${issue.message}`);
156
- }
157
- console.log('');
158
- }
159
-
160
- const cleanFiles = files.length - new Set(allIssues.map(i => i.file)).size;
161
- if (cleanFiles > 0) {
162
- console.log(`✅ No issues found in ${cleanFiles} file${cleanFiles !== 1 ? "s" : ""}`);
163
- }
164
-
165
- console.log(`Summary: ${files.length} files scanned | ${allIssues.length} issue${allIssues.length !== 1 ? "s" : ""} (${errors.length} critical, ${warnings.length} high/medium)`);
166
- process.exit(errors.length > 0 ? 1 : 0);
167
- }
168
-
169
- main();