codebase

A modern TypeScript codebase with Nx, featuring automated releases, comprehensive code quality tools, and strict type safety.

💽 Projects

• 🤲 affirmations - Python LangChain + Ollama affirmation generator (LangGraph ReAct agent, SearxNG)
• 🛰️ caelundas - Swiss Ephemeris calendar generator that turns astronomical events into an .ics file
• 🔭 callidescope - Call stack tracing toolchain that follows control flow through injected dependencies and reports where a stack got too deep
  • callidescope-agents - Agent skills for the callidescope toolchain, published and installed back from the lockfile like any other vendored skill
  • callidescope-cli - Command-line host that builds the call graph with the TypeScript compiler API, resolves NestJS injected dependencies, and reports the deepest stack below every entry point
  • callidescope-configuration - Reads callidescope.config.ts for entry-point rules, depth and cohesion limits, exclusion globs, and output destinations
  • callidescope-examples - A small codebase built to be traced, carrying one worked example per rule, finding, and output the toolchain has
  • callidescope-graph - Builds the call graph from traced TypeScript source and measures its depth, breadth, and cohesion
  • callidescope-nx - Nx plugin inferring per-project trace, depth, and breadth targets that follow the Nx dependency graph, keeping every Nx dependency out of the packages that trace
  • callidescope-output - Renders call-graph findings into markdown, mermaid, and JSON output formats
• 🕸️ codependix - Dependency graph export toolchain that reads what each project depends on, renders it as JSON and Markdown diagrams, and gates the rules those graphs are judged against
  • codependix-agents - Agent skills for the codependix toolchain, installable by any workspace that uses codependix
  • codependix-boundaries - Builds each level's graph for a workspace, judges it against the declared rules, and reports the edges and cycles that break them
  • codependix-cli - Command-line host that exports a project's Nx, NestJS, and file-level dependency graphs as JSON and Markdown anchor blocks, and gates the rules over them
  • codependix-configuration - Reads codependix.config.ts and resolves per-project export destinations and boundary rules
  • codependix-examples - Sixteen subjects built to be graphed, each carrying the guide codependix renders from it
  • codependix-imports - Builds a project's file-level import graph — a typescript module walking its own ts.Program, and a python module parsing import/from ... import statements
  • codependix-nestjs - Explores a NestJS project's container and builds its module graph
  • codependix-nx - Builds a project's one-hop Nx dependency neighborhood from the Nx project graph
• ⏲️ codometer - Repository measurement toolchain that counts a codebase and reports what it found
  • codometer-agents - Agent skills for the codometer toolchain, published and installed back from the lockfile like any other vendored skill
  • codometer-changes - Diffs codometer reports against a baseline snapshot
  • codometer-cli - Command-line host that measures TypeScript, JavaScript, Python, JSON, markdown, and Jupyter notebooks, then writes the badge block in this README, a JSON report, or both
  • codometer-configuration - Reads codometer.config.ts for exclusion globs, output destinations and their render/write callbacks, and the Python interpreter
  • codometer-customization - Evaluates codometer's configured custom counters
  • codometer-discovery - Glob matching and gitignore-aware file walking, plus resolving configured measurement targets to file sets
  • codometer-examples - A sample corpus with known contents and one runnable example per thing codometer does, with tests that assert every number the guides quote
  • codometer-languages - Every input language analyzer codometer measures, behind one analyze() call
  • codometer-output - Every codometer output format - JSON reports, README badges, and the pull request change report
  • codometer-size - Compresses a target's matched files and measures their size
• 👔 conformetry - Template-driven code generation and conformance validation toolchain
  • conformetry-agents - Agent skills for the conformetry toolchain, published and installed back from the lockfile like any other vendored skill
  • conformetry-cli - Command-line host that expands globs, prompts for inputs, and runs generation and validation
  • conformetry-configuration - Configuration loading, template discovery, and generator input resolution
  • conformetry-core - Shared error types, language validator contracts, and finding reporting
  • conformetry-examples - Eleven runnable examples of the toolchain, each with its own configuration, template, instances, and guide, executed by CI so the guides cannot rot
  • conformetry-files - Checks that every file a template declares exists, whatever its extension
  • conformetry-generation - Mustache template rendering and scaffold file generation
  • conformetry-languages - Every language conformetry compares files with, as modules of one package, plus the resolution that picks them and the text fallback
  • conformetry-nx - Nx plugin host with generators, executors, and the emitted-plugin bootstrap
  • conformetry-validation - Validation orchestration, language routing, and finding deduplication
• infrastructure - Helm charts, Terraform, Kubernetes infrastructure
• JimmyPaolini - GitHub profile site
• 🐺 lexico - Latin-English dictionary suite: the web application, its components, its schema, and the ingestion that fills it
  • lexico - TanStack Start SSR dictionary web application
  • lexico-components - Shared React component library using shadcn/ui and Radix primitives
  • lexico-entities - TypeORM entities, migrations, and grammatical enumerations for the dictionary and literature schema
  • lexico-ingestion - NestJS CLI that scrapes and loads dictionary, literature, and etymology sources
• 🪵 logger - Shared pino-backed NestJS LoggerService and LoggerModule
• 🌀 meanderaw - CLI that generates Greek meander (key/fret) SVG patterns programmatically from a type, row count, and repeat count
• ↔️ synchronization - NestJS CLI that regenerates the workspace's derived configuration and documentation, and fails CI when they drift
• 🧑‍⚖️ validation - NestJS CLI for the repository's one-sided checks, the ones with a check and no write, such as the pull request metadata gate

📖 Documentation

Getting Started & Workflow

• Contributing Guide - Start here. Local and dev container setup, the commands to run, code standards, branch and commit conventions, pull requests, and releases
• AGENTS.md - Commands, project layout, conventions, code quality gates, and git workflow
• Release Process - Automated semantic versioning and changelogs

Architecture & Systems

• CI/CD Workflows - GitHub Actions workflows and the shared setup-codebase composite action
• Infrastructure - Helm charts, Terraform, and the Kubernetes deployment pipeline
• Dev Container - Containerized development environment
• Scripts - Local setup and maintenance scripts

Conventions & Guidelines

Conventions live in AGENTS.md and the agent skills below, which are the single sources of truth. Every project also has its own AGENTS.md with project-specific patterns.

🤖 Agent Skills (Domain Knowledge) Skills are specialized instruction files used by our automated agents, but they also serve as excellent deep-dive documentation for human developers.

• View all Skills - Complete index of available skills
• Languages: TypeScript / React / Python / Comments
• Quality: Validate Code / Testing Strategy / Testing Mocks / Error Handling
• Workflows: Git Commits / PR Management / Branch Naming
• Tooling: Nx Workspaces / Generators / Task Running
• Triage: Failing CI / Rejected Commits / Spell Check

Other important files include CHANGELOG.md and SECURITY.md.

👔 Conformetry

Template-driven code generation and conformance validation, templates synced from configuration/conformetry.config.ts by nx run synchronization:conformetry-generators:write.

<!-- conformetry-generators-table start -->

<!-- conformetry-generators-table end -->

🕸️ Codependix

The workspace's dependency graph, exported by codependix, regenerated by nx run codebase:codependix:write.

<!-- codependix:start name="codependix-workspace" -->

graph LR
  affirmations["affirmations"]
  caelundas["caelundas"]
  callidescope_agents["callidescope-agents"]
  callidescope_cli["callidescope-cli"]
  callidescope_configuration["callidescope-configuration"]
  callidescope_examples["callidescope-examples"]
  callidescope_graph["callidescope-graph"]
  callidescope_nx["callidescope-nx"]
  callidescope_output["callidescope-output"]
  codependix_agents["codependix-agents"]
  codependix_boundaries["codependix-boundaries"]
  codependix_cli["codependix-cli"]
  codependix_configuration["codependix-configuration"]
  codependix_examples["codependix-examples"]
  codependix_imports["codependix-imports"]
  codependix_nestjs["codependix-nestjs"]
  codependix_nx["codependix-nx"]
  codometer_agents["codometer-agents"]
  codometer_changes["codometer-changes"]
  codometer_cli["codometer-cli"]
  codometer_configuration["codometer-configuration"]
  codometer_customization["codometer-customization"]
  codometer_discovery["codometer-discovery"]
  codometer_examples["codometer-examples"]
  codometer_languages["codometer-languages"]
  codometer_output["codometer-output"]
  codometer_size["codometer-size"]
  conformetry_agents["conformetry-agents"]
  conformetry_cli["conformetry-cli"]
  conformetry_configuration["conformetry-configuration"]
  conformetry_core["conformetry-core"]
  conformetry_examples["conformetry-examples"]
  conformetry_files["conformetry-files"]
  conformetry_generation["conformetry-generation"]
  conformetry_languages["conformetry-languages"]
  conformetry_nx["conformetry-nx"]
  conformetry_validation["conformetry-validation"]
  lexico["lexico"]
  lexico_components["lexico-components"]
  lexico_entities["lexico-entities"]
  lexico_ingestion["lexico-ingestion"]
  logger["logger"]
  meanderaw["meanderaw"]
  synchronization["synchronization"]
  validation["validation"]
  caelundas --> logger
  callidescope_cli --> callidescope_configuration
  callidescope_cli --> callidescope_graph
  callidescope_cli --> callidescope_output
  callidescope_cli --> logger
  callidescope_examples -.-> callidescope_cli
  callidescope_examples --> callidescope_configuration
  callidescope_graph --> callidescope_configuration
  callidescope_graph --> logger
  callidescope_nx --> callidescope_cli
  callidescope_nx --> callidescope_configuration
  callidescope_nx --> callidescope_graph
  callidescope_nx --> callidescope_output
  callidescope_nx --> logger
  callidescope_output --> callidescope_configuration
  callidescope_output --> callidescope_graph
  callidescope_output --> logger
  codependix_boundaries --> codependix_configuration
  codependix_boundaries --> codependix_imports
  codependix_boundaries --> codependix_nestjs
  codependix_boundaries --> codependix_nx
  codependix_cli --> codependix_boundaries
  codependix_cli --> codependix_configuration
  codependix_cli --> codependix_imports
  codependix_cli --> codependix_nestjs
  codependix_cli --> codependix_nx
  codependix_cli --> logger
  codependix_examples --> codependix_boundaries
  codependix_examples --> codependix_cli
  codependix_examples --> codependix_configuration
  codependix_examples --> codependix_imports
  codependix_examples --> codependix_nestjs
  codependix_examples --> codependix_nx
  codependix_examples --> logger
  codependix_nestjs --> logger
  codometer_changes --> logger
  codometer_cli --> codometer_changes
  codometer_cli --> codometer_configuration
  codometer_cli --> codometer_customization
  codometer_cli --> codometer_discovery
  codometer_cli --> codometer_languages
  codometer_cli --> codometer_output
  codometer_cli --> codometer_size
  codometer_cli --> logger
  codometer_customization --> codometer_configuration
  codometer_customization --> codometer_languages
  codometer_discovery --> codometer_configuration
  codometer_discovery --> logger
  codometer_examples --> codometer_cli
  codometer_examples --> codometer_configuration
  codometer_languages --> codometer_configuration
  codometer_languages --> logger
  codometer_output --> codometer_changes
  codometer_output --> codometer_configuration
  codometer_output --> logger
  codometer_size --> codometer_configuration
  codometer_size --> logger
  conformetry_cli --> conformetry_configuration
  conformetry_cli --> conformetry_core
  conformetry_cli --> conformetry_generation
  conformetry_cli --> conformetry_validation
  conformetry_cli --> logger
  conformetry_configuration --> conformetry_core
  conformetry_configuration --> conformetry_generation
  conformetry_examples -.-> conformetry_cli
  conformetry_examples --> conformetry_configuration
  conformetry_examples --> conformetry_core
  conformetry_examples --> conformetry_generation
  conformetry_examples --> conformetry_nx
  conformetry_examples --> conformetry_validation
  conformetry_files --> conformetry_configuration
  conformetry_files --> conformetry_core
  conformetry_languages --> conformetry_core
  conformetry_nx --> conformetry_configuration
  conformetry_nx --> conformetry_core
  conformetry_nx --> conformetry_generation
  conformetry_nx --> conformetry_validation
  conformetry_nx --> logger
  conformetry_validation --> conformetry_configuration
  conformetry_validation --> conformetry_core
  conformetry_validation --> conformetry_files
  conformetry_validation --> conformetry_languages
  lexico --> lexico_components
  lexico_ingestion --> lexico_entities
  lexico_ingestion --> logger
  meanderaw --> logger
  synchronization --> conformetry_configuration
  synchronization --> logger
  validation --> logger

Dashed edges are dependencies Nx inferred from configuration rather than from code.

<!-- codependix:end name="codependix-workspace" -->

<!-- CODE_STATISTICS_START -->

⏲️ Codometer

Repository statistics measured by codometer, regenerated by nx run codebase:codometer.

Repository

TypeScript

JavaScript

Python

JSON

YAML

TOML

Shell

SQL

HCL

CSS

Conventions

Jupyter

Markdown

<!-- CODE_STATISTICS_END -->

<!-- CALL_STACKS_START -->

🔭 Callidescope

The workspace's call graph, traced by callidescope, regenerated by nx run codebase:callidescope:write. Projects are listed tightest-first: the rows at the top are the ones a ratchet cannot descend past.

Projects

Depth headroom

Call stacks over the depth limit (4)

1. JupyterService.validateDocument — depth 13 · orphan-root

🚀 JupyterService.validateDocument(document: PreparedValidationDocument): DocumentValidationResult [packages/conformetry-languages/src/modules/jupyter/jupyter.service.ts:153]
   ↳ Reports every notebook difference: envelope, missing cells, cell contents.
  └─> JupyterService.map(…)(…): { error: { differenceType: "code"; expected: string; fix: string; language: "python"; message: string; weight: number; }; weight: number; } [packages/conformetry-languages/src/modules/jupyter/jupyter.service.ts:173]
    └─> JupyterService.weighMissingCell(args: { cell: PairedCells; document: PreparedValidationDocument; }): number [packages/conformetry-languages/src/modules/jupyter/jupyter.service.ts:140]
       ↳ Weighs a cell the notebook does not have.
      └─> JupyterService.validateCell(…): DocumentValidationResult [packages/conformetry-languages/src/modules/jupyter/jupyter.service.ts:90]
         ↳ Validates one paired cell with the validator matching its kind.
        └─> MarkdownService.validateDocument(document: PreparedValidationDocument): DocumentValidationResult [packages/conformetry-languages/src/modules/markdown/markdown.service.ts:48]
           ↳ Reports every markdown structure the template requires and the file lacks.
          └─> MarkdownTreeService.compareContainer(args: CompareNodeArguments): CompareNodeResult (cycle) [packages/conformetry-languages/src/modules/markdown/markdown-tree.service.ts:64]
             ↳ Matches a container node, then descends into it.
            └─> MarkdownTreeService.map(…)(…): { differences: MarkdownComparisonError[]; lastMatchedNode: MarkdownNode; totalWeight: number; } (cycle) [packages/conformetry-languages/src/modules/markdown/markdown-tree.service.ts:90]
              └─> MarkdownTreeService.compareChildren(args: CompareChildrenArguments): CompareChildrenResult (cycle) [packages/conformetry-languages/src/modules/markdown/markdown-tree.service.ts:146]
                 ↳ Compares one level of two trees, descending into containers.
                └─> MarkdownTreeService.compareLeaf(args: CompareNodeArguments): CompareNodeResult [packages/conformetry-languages/src/modules/markdown/markdown-tree.service.ts:114]
                   ↳ Matches a leaf node on its own identity, without descending.
                  └─> MarkdownTreeService.findCandidates(args: CompareNodeArguments): MarkdownNode[] [packages/conformetry-languages/src/modules/markdown/markdown-tree.service.ts:134]
                     ↳ Finds every instance sibling satisfying the template node.
                    └─> MarkdownTreeService.filter(…)(instanceNode: MarkdownNode): boolean [packages/conformetry-languages/src/modules/markdown/markdown-tree.service.ts:135]
                      └─> MarkdownNodesService.matches(args: { instanceNode: MarkdownNode; templateNode: MarkdownNode; }): boolean [packages/conformetry-languages/src/modules/markdown/markdown-nodes.service.ts:140]
                         ↳ Returns whether an instance node satisfies a template node.
                        └─> MarkdownNodesService.readText(node: MarkdownNode): string [packages/conformetry-languages/src/modules/markdown/markdown-nodes.service.ts:163]
                           ↳ Reads a node's rendered plain text.

2. JsonService.validateDocument — depth 12 · orphan-root

🚀 JsonService.validateDocument(document: PreparedValidationDocument): DocumentValidationResult [packages/conformetry-languages/src/modules/json/json.service.ts:39]
   ↳ Reports every key or value the template requires and the instance lacks.
  └─> JsonComparisonService.compareArrayItem(…): JsonComparison (cycle) [packages/conformetry-languages/src/modules/json/json-comparison.service.ts:79]
     ↳ Matches one required array entry against the instance array.
    └─> JsonComparisonService.map(…)(instanceItem: JsonValue, index: number): JsonComparison (cycle) [packages/conformetry-languages/src/modules/json/json-comparison.service.ts:122]
      └─> JsonComparisonService.compare(args: CompareJsonArguments): JsonComparison (cycle) [packages/conformetry-languages/src/modules/json/json-comparison.service.ts:268]
         ↳ Compares a template value against an instance value, returning every way the instance fails to contain what the…
        └─> JsonComparisonService.compareArrays(…): JsonComparison (cycle) [packages/conformetry-languages/src/modules/json/json-comparison.service.ts:141]
           ↳ Compares two arrays.
          └─> JsonComparisonService.map(…)(templateItem: JsonValue): JsonComparison (cycle) [packages/conformetry-languages/src/modules/json/json-comparison.service.ts:148]
            └─> JsonComparisonService.compareObjects(…): JsonComparison (cycle) [packages/conformetry-languages/src/modules/json/json-comparison.service.ts:155]
               ↳ Compares two objects, requiring every template key to be present.
              └─> JsonComparisonService.map(…)([key, templateValue]: [string, JsonValue]): JsonComparison (cycle) [packages/conformetry-languages/src/modules/json/json-comparison.service.ts:164]
                └─> JsonComparisonService.countNodes(value: JsonValue): number (cycle) [packages/conformetry-languages/src/modules/json/json-comparison.service.ts:207]
                   ↳ Counts a JSON value and every value nested inside it.
                  └─> JsonComparisonService.reduce(…)(total: number, item: JsonValue): number (cycle) [packages/conformetry-languages/src/modules/json/json-comparison.service.ts:209]
                    └─> JsonComparisonService.reduce(…)(total: number, nested: JsonValue): number (cycle) [packages/conformetry-languages/src/modules/json/json-comparison.service.ts:215]
                      └─> JsonComparisonService.isJsonObject(value: JsonValue): value is Record<string, JsonValue> [packages/conformetry-languages/src/modules/json/json-comparison.service.ts:235]
                         ↳ Returns whether a value is a plain JSON object.