Node.js Utility Scripts
Relevant source files
The following files were used as context for generating this wiki page:
Node.js utility scripts within the Everything Claude Code (ECC) project serve as the operational backbone for codebase maintenance, automated documentation generation, and continuous integration validation. These scripts automate complex tasks such as mapping the project architecture, validating command definitions, and generating readiness dashboards for operators.
These utilities are primarily located in the scripts/ directory and are often invoked via npx or as part of the project's agentic workflows, such as those defined for the doc-updater or operator-readiness systems. Sources: AGENTS.md:103, scripts/codemaps/generate.ts:16-25
Architectural Overview
The utility script ecosystem is designed around a "single source of truth" principle, where scripts extract metadata directly from source files, configuration files (like package.json or .env.example), and git history to ensure documentation and validation artifacts remain synchronized with the actual code state. Sources: agents/doc-updater.md:65, commands/update-docs.md:9-16
The diagram above illustrates how utility scripts ingest data from various project sources to produce structured documentation and validation results. Sources: scripts/codemaps/generate.ts:31-50, scripts/ci/validate-commands.js:10-15, tests/scripts/operator-readiness-dashboard.test.js:28-40
Key Utility Modules
Codemap Generator (generate.ts)
The Codemap Generator is a TypeScript utility used to scan the workspace and generate architectural documentation. It classifies files into specific "areas" using regex patterns and builds directory trees to visualize the repository structure. Sources: scripts/codemaps/generate.ts:4-15
- Area Classification: Files are sorted into categories:
frontend,backend,database,integrations, andworkers. Sources: scripts/codemaps/generate.ts:31-54 - Metrics Collection: The script calculates file counts and total lines per area. Sources: scripts/codemaps/generate.ts:141-143
- Tree Generation: It builds a 3-level deep ASCII directory tree for the
INDEX.mdoverview. Sources: scripts/codemaps/generate.ts:114-135
| Area | Identification Patterns |
|---|---|
| Frontend | /app/, /pages/, .tsx, .vue, .svelte |
| Backend | /api/, /routes/, /controllers/, .service.ts |
| Database | /models/, /migrations/, schema.prisma, schema.sql |
| Integrations | /third-party/, /adapters/, .connector.ts |
| Workers | /workers/, /queues/, .cron.ts |
Sources: scripts/codemaps/generate.ts:31-54
Command Validator (validate-commands.js)
This script ensures the integrity of the project's slash command documentation. It performs static analysis on markdown files located in the commands/ directory to detect broken links and invalid metadata. Sources: scripts/ci/validate-commands.js:1-6
- Frontmatter Validation: Checks for valid YAML-like frontmatter blocks and proper quoting of complex values. Sources: scripts/ci/validate-commands.js:17-57
- Cross-Reference Checking: Validates that
/commandreferences point to existing files and thatagents/orskills/paths are accurate. Sources: scripts/ci/validate-commands.js:106-135 - Workflow Verification: Ensures that agent sequence diagrams (e.g.,
planner -> tdd-guide) use valid agent identifiers. Sources: scripts/ci/validate-commands.js:141-152
Operator Readiness Dashboard
The operator dashboard script (tested in operator-readiness-dashboard.test.js) generates a status report for project releases. It aggregates data from roadmap files, publication checklists, and security scan results. Sources: tests/scripts/operator-readiness-dashboard.test.js:1-10
Automated Documentation Workflows
The utility scripts are integrated into higher-level documentation update processes. These processes emphasize extracting information from "sources of truth" rather than manual entry. Sources: commands/update-docs.md:4-6
- Script Reference Extraction: Commands are pulled from
package.jsonorMakefileto generate a command reference table. Sources: commands/update-docs.md:18-28 - Environment Sync: Environment variables are parsed from
.env.exampleto document required vs. optional configurations. Sources: commands/update-docs.md:30-41 - Staleness Auditing: Scripts identify documentation files not modified in over 90 days for review. Sources: commands/update-docs.md:58-62
Example: Script Reference Generation Logic
// Logic used to generate documentation from package.json
const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
const scripts = pkg.scripts || {};
const table = Object.entries(scripts).map(([name, cmd]) => {
return `| \`${name}\` | ${cmd} |`;
}).join('\n');
Sources: commands/update-docs.md:23-28, tests/scripts/operator-readiness-dashboard.test.js:28-45
Maintenance and Quality Standards
All utility scripts are subject to the same quality standards as the core application.
- Error Handling: Scripts must handle missing files or invalid JSON gracefully, providing clear error messages rather than failing silently. Sources: scripts/codemaps/generate.ts:80-85, scripts/ci/validate-commands.js:100-104
- Output Formatting: Artifacts should include "last updated" timestamps and, where applicable,
<!-- AUTO-GENERATED -->markers to prevent accidental manual overwrites. Sources: scripts/codemaps/generate.ts:141, commands/update-docs.md:73-75 - Path Resolution: Scripts use relative path resolution to remain portable across different user environments. Sources: scripts/codemaps/generate.ts:27-29, commands/update-docs.md:8
Summary
Node.js utility scripts provide the necessary automation to keep the ECC project manageable at scale. By automating architectural mapping, command validation, and documentation synchronization, these tools ensure that developers and operators have access to accurate, real-time information about the codebase state and its operational readiness. Sources: agents/doc-updater.md:14-19, scripts/codemaps/generate.ts:208-215