forgecraft-mcp 0.1.0

package/README.md

@@ -0,0 +1,251 @@
+<p align="center">
+  <h1 align="center">ForgeCraft</h1>
+  <p align="center">
+    <strong>Give Claude Code real engineering standards. Automatically.</strong>
+  </p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/forgecraft-mcp"><img src="https://img.shields.io/npm/v/forgecraft-mcp.svg" alt="npm version"></a>
+    <a href="https://github.com/jghiringhelli/forgecraft-mcp/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/forgecraft-mcp.svg" alt="license"></a>
+    <a href="https://www.npmjs.com/package/forgecraft-mcp"><img src="https://img.shields.io/npm/dm/forgecraft-mcp.svg" alt="downloads"></a>
+  </p>
+</p>
+
+---
+
+`claude init` gets you started — it scans your project and generates a basic CLAUDE.md. That's a great first step.
+
+**ForgeCraft is the next step.**
+
+`claude init` gives you a generic starting point. ForgeCraft gives you production engineering standards: SOLID principles, testing pyramids with coverage targets, architecture patterns, CI/CD pipelines, domain-specific rules, and quality-gate hooks — all composed from 112 curated template blocks matched to your actual stack.
+
+```bash
+claude mcp add forgecraft -- npx -y forgecraft-mcp
+```
+
+Then tell Claude:
+
+> "Set up this project for production"
+
+Done. Claude now has a tailored CLAUDE.md with SOLID principles, testing standards, architecture patterns, CI/CD guidance, and quality-gate hooks — all matched to your stack.
+
+## `claude init` vs ForgeCraft
+
+| | `claude init` | ForgeCraft |
+|---|---|---|
+| **CLAUDE.md** | Generic, one-size-fits-all | 112 curated blocks matched to your stack |
+| **Architecture** | None | SOLID, hexagonal, clean code, DDD |
+| **Testing** | Basic mention | Testing pyramid with coverage targets (80%+) |
+| **Domain rules** | None | 18 domains (fintech, healthcare, gaming…) |
+| **Commit standards** | None | Conventional commits, atomic changes |
+| **Quality gates** | None | Pre-commit hooks that enforce standards |
+| **CI/CD** | None | Pipeline stages, environments, deploy guidance |
+| **Session continuity** | None | `Status.md` + `forgecraft.yaml` persist context |
+| **Drift detection** | None | `refresh_project` detects scope changes |
+| **Compliance scoring** | None | `audit_project` scores 0-100 |
+
+## How It Works
+
+```
+You: "Set up this project for production"
+
+Claude calls setup_project → scans your code → detects [API] + [WEB-REACT]
+                           → creates forgecraft.yaml
+                           → generates CLAUDE.md from 112 curated template blocks
+                           → adds quality-gate hooks
+                           → done
+```
+
+ForgeCraft is an [MCP server](https://modelcontextprotocol.io/) — it gives Claude 14 specialized tools. Claude picks the right ones automatically. You just describe what you want in plain English.
+
+> **Already ran `claude init`?** ForgeCraft's `generate_claude_md` can merge with your existing CLAUDE.md (`merge_with_existing: true`), keeping your custom sections while adding production standards.
+
+## Install
+
+**One line. Takes 10 seconds.**
+
+```bash
+claude mcp add forgecraft -- npx -y forgecraft-mcp
+```
+
+Restart Claude Code. That's it.
+
+<details>
+<summary>Alternative: manual config</summary>
+
+Add to `.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "forgecraft": {
+      "command": "npx",
+      "args": ["-y", "forgecraft-mcp"]
+    }
+  }
+}
+```
+</details>
+
+## What You Get
+
+After `setup_project`, your project has:
+
+```
+your-project/
+├── forgecraft.yaml        ← Your config (tags, tier, customizations)
+├── CLAUDE.md              ← Engineering standards tailored to your stack
+├── Status.md              ← Session continuity tracker
+├── .claude/hooks/         ← Pre-commit quality gates
+├── docs/
+│   ├── PRD.md             ← Requirements skeleton
+│   └── TechSpec.md        ← Architecture + NFR sections
+└── src/shared/            ← Config, errors, logger starters
+```
+
+### The CLAUDE.md
+
+This is the core value. Assembled from curated blocks covering:
+
+- **SOLID principles** — concrete rules, not platitudes
+- **Hexagonal architecture** — ports, adapters, DTOs, layer boundaries
+- **Testing pyramid** — unit/integration/E2E targets, test doubles taxonomy
+- **Clean code** — CQS, guard clauses, immutability, pure functions
+- **CI/CD & deployment** — pipeline stages, environments, preview deploys
+- **Domain patterns** — DDD, CQRS, event sourcing (when your project needs it)
+- **12-Factor ops** — config, statelessness, disposability, logging
+
+Every block is sourced from established engineering literature (Martin, Evans, Wiggins) and adapted for AI-assisted development.
+
+## 18 Tags — Pick What Fits
+
+Tags are domain classifiers. ForgeCraft auto-detects them from your code, or you choose manually. Combine freely — blocks merge without conflicts.
+
+| Tag | What it adds |
+|-----|-------------|
+| `UNIVERSAL` | SOLID, testing, commits, error handling *(always on)* |
+| `API` | REST/GraphQL contracts, auth, rate limiting, versioning |
+| `WEB-REACT` | Component arch, state management, a11y, perf budgets |
+| `WEB-STATIC` | Build optimization, SEO, CDN, static deploy |
+| `CLI` | Arg parsing, output formatting, exit codes |
+| `LIBRARY` | API design, semver, backwards compatibility |
+| `INFRA` | Terraform/CDK, Kubernetes, secrets management |
+| `DATA-PIPELINE` | ETL, idempotency, checkpointing, schema evolution |
+| `ML` | Experiment tracking, model versioning, reproducibility |
+| `FINTECH` | Double-entry accounting, decimal precision, compliance |
+| `HEALTHCARE` | HIPAA, PHI handling, audit logs, encryption |
+| `MOBILE` | React Native/Flutter, offline-first, native APIs |
+| `REALTIME` | WebSockets, presence, conflict resolution |
+| `GAME` | Game loop, ECS, physics, rendering pipeline |
+| `SOCIAL` | Feeds, connections, messaging, moderation |
+| `ANALYTICS` | Event tracking, dashboards, data warehousing |
+| `STATE-MACHINE` | Transitions, guards, event-driven workflows |
+| `WEB3` | Smart contracts, gas optimization, wallet security |
+
+## Content Tiers
+
+Not every project needs DDD on day one.
+
+| Tier | Includes | Best for |
+|------|----------|----------|
+| **core** | Code standards, testing, commit protocol | New/small projects |
+| **recommended** | + architecture, CI/CD, clean code, deploy | Most projects *(default)* |
+| **optional** | + DDD, CQRS, event sourcing, design patterns | Mature teams, complex domains |
+
+Set in `forgecraft.yaml`:
+```yaml
+projectName: my-api
+tags: [UNIVERSAL, API]
+tier: recommended
+```
+
+## All 14 Tools
+
+| Tool | Purpose |
+|------|---------|
+| `setup_project` | **Start here.** Analyze → classify → configure → generate. |
+| `refresh_project` | Re-scan after changes. Detects new tags, updates config. |
+| `classify_project` | Analyze code to suggest tags |
+| `scaffold_project` | Generate full project structure |
+| `generate_claude_md` | Create/regenerate CLAUDE.md |
+| `audit_project` | Score compliance (0-100). Run in CI. |
+| `review_project` | Structured review checklist |
+| `convert_existing` | Phased migration plan for legacy code |
+| `add_hook` | Add quality-gate hooks |
+| `add_module` | Scaffold a feature module |
+| `configure_mcp` | Generate `.claude/settings.json` |
+| `get_nfr_template` | NFR sections for tech specs |
+| `list_tags` | Show all available tags |
+| `list_hooks` | Show hooks, filterable by tag |
+
+## Configuration
+
+### Fine-tune what Claude sees
+
+```yaml
+# forgecraft.yaml
+projectName: my-api
+tags: [UNIVERSAL, API, FINTECH]
+tier: recommended
+
+exclude:
+  - cqrs-event-patterns    # Don't need this yet
+
+variables:
+  coverage_minimum: 90      # Override defaults
+  max_file_length: 400
+```
+
+### Community template packs
+
+```yaml
+templateDirs:
+  - ./my-company-standards
+  - node_modules/@my-org/forgecraft-flutter/templates
+```
+
+## Keeping Standards Fresh
+
+### Audit (run anytime, or in CI)
+
+```
+Score: 72/100  Grade: C
+
+✅ CLAUDE.md exists
+✅ Hooks installed (3/3)
+✅ Test script configured
+🔴 hardcoded_url: src/auth/service.ts
+🔴 status_md_current: not updated in 12 days
+🟡 lock_file: not committed
+```
+
+### Refresh (project scope changed?)
+
+Tell Claude *"refresh this project"* — it re-scans, suggests new tags, shows before/after impact, and updates everything on approval.
+
+## Contributing
+
+Templates are YAML, not code. You can add patterns without writing TypeScript.
+
+```
+templates/your-tag/
+├── claude-md.yaml      # CLAUDE.md blocks (with tier metadata)
+├── structure.yaml      # Folder structure
+├── nfr.yaml            # Non-functional requirements
+├── hooks.yaml          # Quality gate scripts
+└── review.yaml         # Code review checklists
+```
+
+PRs welcome. See [`templates/universal/`](templates/universal/) for the format.
+
+## Development
+
+```bash
+git clone https://github.com/jghiringhelli/forgecraft-mcp.git
+cd forgecraft-mcp
+npm install
+npm run build
+npm test   # 111 tests, 9 suites
+```
+
+## License
+
+MIT

package/dist/analyzers/anti-pattern.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Anti-pattern detector.
+ *
+ * Scans source files for production code anti-patterns:
+ * hardcoded values, mock data in source, monolith files, etc.
+ */
+import type { AuditCheck } from "../shared/types.js";
+/** Anti-pattern scan configuration. */
+interface ScanConfig {
+    readonly maxFileLength: number;
+    readonly maxFunctionParams: number;
+}
+/**
+ * Scan project source files for anti-patterns.
+ */
+export declare function scanAntiPatterns(projectDir: string, config?: Partial<ScanConfig>): {
+    violations: AuditCheck[];
+    warnings: AuditCheck[];
+};
+export {};
+//# sourceMappingURL=anti-pattern.d.ts.map

package/dist/analyzers/anti-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anti-pattern.d.ts","sourceRoot":"","sources":["../../src/analyzers/anti-pattern.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIrD,uCAAuC;AACvC,UAAU,UAAU;IAClB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAOD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,OAAO,CAAC,UAAU,CAAM,GAC/B;IAAE,UAAU,EAAE,UAAU,EAAE,CAAC;IAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;CAAE,CA+FtD"}

package/dist/analyzers/anti-pattern.js

@@ -0,0 +1,130 @@
+/**
+ * Anti-pattern detector.
+ *
+ * Scans source files for production code anti-patterns:
+ * hardcoded values, mock data in source, monolith files, etc.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, extname } from "node:path";
+import { createLogger } from "../shared/logger/index.js";
+import { listAllFiles } from "./folder-structure.js";
+const logger = createLogger("analyzers/anti-pattern");
+const DEFAULT_CONFIG = {
+    maxFileLength: 300,
+    maxFunctionParams: 5,
+};
+/**
+ * Scan project source files for anti-patterns.
+ */
+export function scanAntiPatterns(projectDir, config = {}) {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    const violations = [];
+    const warnings = [];
+    const allFiles = listAllFiles(projectDir);
+    const sourceFiles = allFiles.filter((f) => isSourceFile(f) && !isTestFile(f));
+    logger.info("Scanning for anti-patterns", {
+        totalFiles: allFiles.length,
+        sourceFiles: sourceFiles.length,
+    });
+    for (const relPath of sourceFiles) {
+        const fullPath = join(projectDir, relPath);
+        if (!existsSync(fullPath))
+            continue;
+        try {
+            const content = readFileSync(fullPath, "utf-8");
+            const lines = content.split("\n");
+            // Check file length
+            if (lines.length > cfg.maxFileLength) {
+                warnings.push({
+                    check: "file_length",
+                    message: `${relPath}: ${lines.length} lines (max ${cfg.maxFileLength}). Consider splitting.`,
+                    severity: "warning",
+                });
+            }
+            // Check for hardcoded URLs (skip config files)
+            if (!isConfigFile(relPath)) {
+                const urlMatches = findPattern(lines, /(localhost|127\.0\.0\.1|0\.0\.0\.0)/, /\/\/|\/\*|\*|#|test|spec|mock/i);
+                if (urlMatches.length > 0) {
+                    violations.push({
+                        check: "hardcoded_url",
+                        message: `${relPath}: hardcoded URL/host at line(s) ${urlMatches.join(", ")}. Use config/env vars.`,
+                        severity: "error",
+                    });
+                }
+            }
+            // Check for mock/stub data in production code
+            const mockMatches = findPattern(lines, /\b(mock_data|fake_data|dummy_data|stub_response|FIXME.*return|TODO.*hardcod)/i);
+            if (mockMatches.length > 0) {
+                violations.push({
+                    check: "mock_in_source",
+                    message: `${relPath}: mock/stub/fake data at line(s) ${mockMatches.join(", ")}. Remove from production code.`,
+                    severity: "error",
+                });
+            }
+            // Check for bare exception catches (TypeScript)
+            if (relPath.endsWith(".ts") || relPath.endsWith(".js")) {
+                const bareCatches = findPattern(lines, /catch\s*\(\s*\)\s*\{/);
+                if (bareCatches.length > 0) {
+                    warnings.push({
+                        check: "bare_exception",
+                        message: `${relPath}: bare catch() at line(s) ${bareCatches.join(", ")}. Use typed error handling.`,
+                        severity: "warning",
+                    });
+                }
+            }
+            // Check for hardcoded credentials
+            const credMatches = findPattern(lines, /(password|secret|api_key|token)\s*[:=]\s*['"][^'"]{3,}/i, /env|config|example|template|schema|type|interface|\/\//i);
+            if (credMatches.length > 0) {
+                violations.push({
+                    check: "hardcoded_credential",
+                    message: `${relPath}: possible hardcoded credential at line(s) ${credMatches.join(", ")}.`,
+                    severity: "error",
+                });
+            }
+        }
+        catch {
+            // Skip unreadable files
+        }
+    }
+    logger.info("Anti-pattern scan complete", {
+        violations: violations.length,
+        warnings: warnings.length,
+    });
+    return { violations, warnings };
+}
+/**
+ * Check if a file is a source code file.
+ */
+function isSourceFile(filePath) {
+    const ext = extname(filePath);
+    return [".ts", ".tsx", ".js", ".jsx", ".py", ".java", ".kt", ".rs"].includes(ext);
+}
+/**
+ * Check if a file is a test file.
+ */
+function isTestFile(filePath) {
+    return /(\btest[_.]|\.test\.|\.spec\.|__tests__|tests\/|test\/|fixtures\/|mock|conftest|\.d\.ts)/.test(filePath);
+}
+/**
+ * Check if a file is a config file.
+ */
+function isConfigFile(filePath) {
+    return /(config|settings|\.env|\.yaml|\.yml|\.json|\.toml)/.test(filePath);
+}
+/**
+ * Find lines matching a pattern, optionally excluding lines matching an exclude pattern.
+ * Returns array of 1-based line numbers.
+ */
+function findPattern(lines, pattern, excludePattern) {
+    const matches = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (pattern.test(line)) {
+            if (!excludePattern || !excludePattern.test(line)) {
+                matches.push(i + 1);
+            }
+        }
+    }
+    return matches;
+}
+//# sourceMappingURL=anti-pattern.js.map

package/dist/analyzers/anti-pattern.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anti-pattern.js","sourceRoot":"","sources":["../../src/analyzers/anti-pattern.ts"],"names":[],"mappings":"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"}

package/dist/analyzers/completeness.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Completeness checker.
+ *
+ * Checks a project against the expected infrastructure for its tags.
+ * Reports what's present, missing, and suggestions.
+ */
+import type { AuditCheck, Tag } from "../shared/types.js";
+/**
+ * Run all completeness checks for a project.
+ */
+export declare function checkCompleteness(projectDir: string, activeTags: Tag[]): {
+    passing: AuditCheck[];
+    failing: AuditCheck[];
+};
+//# sourceMappingURL=completeness.d.ts.map

package/dist/analyzers/completeness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completeness.d.ts","sourceRoot":"","sources":["../../src/analyzers/completeness.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAI1D;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,GAAG,EAAE,GAChB;IAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAA;CAAE,CAqClD"}

package/dist/analyzers/completeness.js

@@ -0,0 +1,207 @@
+/**
+ * Completeness checker.
+ *
+ * Checks a project against the expected infrastructure for its tags.
+ * Reports what's present, missing, and suggestions.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createLogger } from "../shared/logger/index.js";
+const logger = createLogger("analyzers/completeness");
+/**
+ * Run all completeness checks for a project.
+ */
+export function checkCompleteness(projectDir, activeTags) {
+    const passing = [];
+    const failing = [];
+    // UNIVERSAL checks — always run
+    checkFileExists(projectDir, "CLAUDE.md", "claude_md_exists", "CLAUDE.md is the CC instruction set", passing, failing);
+    checkFileExists(projectDir, "Status.md", "status_md_exists", "Status.md enables session continuity", passing, failing);
+    checkFileExists(projectDir, ".env.example", "env_example_exists", ".env.example documents required env vars", passing, failing);
+    // Check Status.md freshness
+    checkStatusMdFreshness(projectDir, passing, failing);
+    // Check hooks
+    checkHooksInstalled(projectDir, passing, failing);
+    // Check docs
+    checkFileExists(projectDir, "docs/PRD.md", "prd_exists", "PRD documents requirements", passing, failing);
+    checkFileExists(projectDir, "docs/TechSpec.md", "tech_spec_exists", "Tech Spec documents architecture", passing, failing);
+    // Check shared modules
+    checkSharedModules(projectDir, passing, failing);
+    // Tag-specific checks
+    if (activeTags.includes("API") || activeTags.includes("LIBRARY")) {
+        checkPackageJson(projectDir, passing, failing);
+    }
+    if (activeTags.includes("WEB-REACT")) {
+        checkFileExists(projectDir, "src/locales", "i18n_setup", "i18n locale files configured", passing, failing);
+    }
+    logger.info("Completeness check done", {
+        passing: passing.length,
+        failing: failing.length,
+    });
+    return { passing, failing };
+}
+/**
+ * Check if a file or directory exists.
+ */
+function checkFileExists(projectDir, relativePath, checkId, description, passing, failing) {
+    const fullPath = join(projectDir, relativePath);
+    if (existsSync(fullPath)) {
+        passing.push({ check: checkId, message: `✅ ${relativePath} exists` });
+    }
+    else {
+        failing.push({
+            check: checkId,
+            message: `${relativePath} is missing — ${description}`,
+            severity: "error",
+        });
+    }
+}
+/**
+ * Check if Status.md was updated recently (within 7 days).
+ */
+function checkStatusMdFreshness(projectDir, passing, failing) {
+    const statusPath = join(projectDir, "Status.md");
+    if (!existsSync(statusPath))
+        return;
+    try {
+        const stat = statSync(statusPath);
+        const daysSinceModified = (Date.now() - stat.mtimeMs) / (1000 * 60 * 60 * 24);
+        if (daysSinceModified <= 7) {
+            passing.push({
+                check: "status_md_current",
+                message: `✅ Status.md updated ${Math.round(daysSinceModified)} day(s) ago`,
+            });
+        }
+        else {
+            failing.push({
+                check: "status_md_current",
+                message: `Status.md not updated in ${Math.round(daysSinceModified)} days — update at end of each session`,
+                severity: "warning",
+            });
+        }
+    }
+    catch {
+        // Can't stat the file, skip this check
+    }
+}
+/**
+ * Check if hook scripts are installed.
+ */
+function checkHooksInstalled(projectDir, passing, failing) {
+    const hooksDir = join(projectDir, ".claude", "hooks");
+    if (!existsSync(hooksDir)) {
+        failing.push({
+            check: "hooks_installed",
+            message: ".claude/hooks/ directory missing — quality gate hooks not installed",
+            severity: "error",
+        });
+        return;
+    }
+    // Check for key hooks
+    const expectedHooks = [
+        "pre-commit-branch-check.sh",
+        "pre-commit-secrets.sh",
+        "pre-commit-compile.sh",
+    ];
+    let hookCount = 0;
+    for (const hookFile of expectedHooks) {
+        if (existsSync(join(hooksDir, hookFile))) {
+            hookCount++;
+        }
+    }
+    if (hookCount === expectedHooks.length) {
+        passing.push({
+            check: "hooks_installed",
+            message: `✅ ${hookCount}/${expectedHooks.length} essential hooks installed`,
+        });
+    }
+    else {
+        failing.push({
+            check: "hooks_installed",
+            message: `Only ${hookCount}/${expectedHooks.length} essential hooks installed`,
+            severity: "warning",
+        });
+    }
+}
+/**
+ * Check for shared modules (config, errors, logging).
+ */
+function checkSharedModules(projectDir, passing, failing) {
+    const sharedPatterns = [
+        { path: "src/shared/config", name: "config module" },
+        { path: "src/shared/errors", name: "error hierarchy" },
+        { path: "src/shared/exceptions", name: "exception hierarchy" },
+    ];
+    let foundShared = false;
+    for (const pattern of sharedPatterns) {
+        if (existsSync(join(projectDir, pattern.path))) {
+            foundShared = true;
+            break;
+        }
+    }
+    if (foundShared) {
+        passing.push({
+            check: "shared_modules",
+            message: "✅ Shared modules (config/errors) present",
+        });
+    }
+    else {
+        failing.push({
+            check: "shared_modules",
+            message: "No shared modules found — create config, errors, logging modules in src/shared/",
+            severity: "warning",
+        });
+    }
+}
+/**
+ * Check package.json for required fields.
+ */
+function checkPackageJson(projectDir, passing, failing) {
+    const pkgPath = join(projectDir, "package.json");
+    if (!existsSync(pkgPath)) {
+        failing.push({
+            check: "package_json",
+            message: "package.json missing",
+            severity: "error",
+        });
+        return;
+    }
+    try {
+        const content = readFileSync(pkgPath, "utf-8");
+        const pkg = JSON.parse(content);
+        // Check for lock file
+        const hasLockFile = existsSync(join(projectDir, "package-lock.json")) ||
+            existsSync(join(projectDir, "pnpm-lock.yaml")) ||
+            existsSync(join(projectDir, "yarn.lock"));
+        if (hasLockFile) {
+            passing.push({ check: "lock_file", message: "✅ Lock file committed" });
+        }
+        else {
+            failing.push({
+                check: "lock_file",
+                message: "No lock file found — commit package-lock.json",
+                severity: "warning",
+            });
+        }
+        // Check for scripts
+        const scripts = pkg["scripts"];
+        if (scripts?.["test"]) {
+            passing.push({ check: "test_script", message: "✅ Test script configured" });
+        }
+        else {
+            failing.push({
+                check: "test_script",
+                message: "No test script in package.json",
+                severity: "warning",
+            });
+        }
+    }
+    catch {
+        failing.push({
+            check: "package_json",
+            message: "package.json could not be parsed",
+            severity: "error",
+        });
+    }
+}
+//# sourceMappingURL=completeness.js.map

package/dist/analyzers/completeness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completeness.js","sourceRoot":"","sources":["../../src/analyzers/completeness.ts"],"names":[],"mappings":"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"}