CLI Tools & Scripts
Relevant source files
The following files were used as context for generating this wiki page:
The TAMV Digital Nexus project employs a specialized suite of CLI tools and scripts designed to enforce the "Constitutional Quality Control" (QC-TAMV-01) framework. These tools operate as automated guardians that ensure architectural integrity, semantic compliance with project values, and code quality through static analysis and dependency graphing.
These scripts are primarily located in the scripts/ directory and are integrated into the development workflow via package.json scripts. They serve as mandatory gates for CI/CD pipelines, preventing any code that violates the project's constitutional "Laws" from being merged or deployed.
Sources: package.json:7-24, scripts/check-architecture.ts:1-12, eslint-plugin-tamv/index.js:1-7
Quality Assurance & Orchestration
The project uses orchestration scripts to execute a sequence of validation steps. The run-checks.sh script acts as a unified entry point for local development, while the ci script in package.json handles the automated pipeline.
Check Execution Flow
The following diagram illustrates the sequential execution of quality checks during a standard validation run.
The orchestration ensures that semantic and constitutional violations are caught early in the process before proceeding to more resource-intensive tests.
Sources: run-checks.sh:1-26, package.json:20
Architectural Invariants (QC-TAMV-01)
The scripts/check-architecture.ts script is the primary tool for validating structural constraints defined in the TAMV constitution. It analyzes the project's dependency graph to detect violations of the "L-series" laws.
Implementation of Constitutional Laws
The script implements several specific validators:
| Law | Name | Description | Severity |
|---|---|---|---|
| L1 | Root Único | ReactDOM.createRoot is only allowed in src/main.tsx. | Error |
| L2 | Router Único | BrowserRouter is only allowed in src/App.tsx. | Error |
| L3 | Layout Único | Layout component import is restricted to src/App.tsx. | Error |
| L4 | Route-Page | Prevents a page from importing another page. | Error |
| L6 | Agnostic Modules | Modules in src/modules/* cannot import navigation or pages. | Error |
| L7 | Controlled Init | Services (e.g., Supabase) should not be directly imported in pages. | Warning |
Sources: scripts/check-architecture.ts:133-247, eslint-plugin-tamv/index.js:12-160
Dependency Analysis Logic
The architecture checker builds a graph of the src/ directory by scanning files and extracting ES6 and dynamic imports using regex patterns.
Semantic & Constitutional Scanning
The scripts/scan-semantics.ts (and its JS equivalent) performs intentional analysis of the codebase. Unlike standard linting, it looks for specific terminology and patterns that violate the project's constitutional framework, such as unauthorized DAO structures or manipulative UI patterns.
Restricted Semantic Patterns
The scanner identifies four primary categories of prohibited patterns:
- DAO-Related:
governance token,community treasury,on-chain governance. - Economic Exploitation:
hidden fee,predatory pricing,surprise charge. - Cognitive Manipulation:
dark pattern,misleading UI,coercive design. - AI Sovereignty:
AI decides,autonomous AI,AI governance.
Citations: [scripts/scan-semantics.ts:18-50](https://github.com/OsoPanda1/tamv-digital-nexus/blob/HEAD/scripts/scan-semantics.ts#L18-L50)
Exception Handling
The scanner allows for specific historical or external references if they are explicitly marked with [HISTORICAL], [EXTERNAL], or [LEGACY] tags.
Sources: scripts/scan-semantics.ts:59-64, eslint-plugin-tamv/index.js:235-240
ESLint Constitutional Plugin
The eslint-plugin-tamv directory contains a custom ESLint plugin that mirrors many of the architectural checks for real-time feedback in the IDE.
Key Rules
const plugin = {
rules: {
'no-reactdom-outside-main': noReactDOMOutsideMain, // L1
'no-router-outside-app': noRouterOutsideApp, // L2
'no-layout-outside-app': noLayoutOutsideApp, // L3
'no-dao': noDao, // Constitutional
'no-hidden-economy': noHiddenEconomy // Transparency
}
};
Sources: eslint-plugin-tamv/index.js:338-348
The no-hidden-economy rule is particularly unique; it triggers an error if economic functions (like processPayment or calculateFee) are detected in a file that lacks UI-related keywords (like tooltip or modal), enforcing transparency.
Sources: eslint-plugin-tamv/index.js:274-307
Command Summary Table
| Command | Script / Path | Purpose |
|---|---|---|
npm run check:architecture | scripts/check-architecture.ts | Validates L1-L7 architectural laws. |
npm run scan:semantics | scripts/scan-semantics.js | Scans for prohibited constitutional patterns. |
npm run lint:constitution | eslint . --plugin tamv | Runs the custom TAMV linter rules. |
npm run ci | (Orchestration) | Runs constitutional lint, semantics, tests, and architecture. |
bash run-checks.sh | run-checks.sh | Shell script for sequential local validation. |
Sources: package.json:11-20, run-checks.sh:1-26
The suite of CLI tools and scripts in the TAMV project ensures that the software remains technically and ethically aligned with the project's core principles. By automating architectural and semantic checks, the system reduces the burden on human review and maintains a high level of structural rigor.