Working with Generated Files¶

This guide explains how to work with generated files in the SyRF monorepo, including the verification system that ensures generated files stay in sync with their sources.

Overview¶

The SyRF monorepo contains 18 generated files produced by 4 generators:

Generator	Source	Output Files
`generate-env-blocks.ts`	`env-mapping.yaml`	7 files (Helm template, config TS/JSON)
`generate-feature-flags.ts`	`env-mapping.yaml`	4 files (feature flag TS files)
`generate-dockerfiles.py`	`dependency-map.yaml`	6 Dockerfiles
NSwag	`swagger.json`	1 file (TypeScript API client)

How Verification Works¶

The system uses a hash-manifest approach stored in .generated-checksums.json:

sourceHash - SHA-256 of source file(s), detects when sources change
outputHash - SHA-256 of each generated file, detects manual edits
generatorHash - SHA-256 of generator script (warning only)

When you commit, the precommit hook validates:

Source files haven't changed without regenerating outputs
Generated files haven't been manually edited

Quick Reference¶

Validation Commands¶

# Validate all generated files
pnpm run validate:generated

# Run individual generator validators
cd src/charts/syrf-common && pnpm run validate:env-blocks
cd src/services/web && pnpm run validate:flags
python scripts/generate-dockerfiles.py --validate

Regeneration Commands¶

# Regenerate config files (7 files)
cd src/charts/syrf-common && pnpm run generate:env-blocks

# Regenerate feature flags (4 files)
cd src/services/web && pnpm run generate:flags

# Regenerate Dockerfiles (6 files)
python scripts/generate-dockerfiles.py

# Regenerate API client (1 file) - requires swagger.json
cd src/services/web && pnpm run nswag:generate

# Regenerate swagger.json from API assembly (requires API build first)
dotnet build src/services/api/SyRF.API.Endpoint -c Release
cd src/services/web && pnpm run nswag:spec

Developer Workflows¶

Modifying env-mapping.yaml¶

When changing environment variables or feature flags:

# 1. Edit the source
vim src/charts/syrf-common/env-mapping.yaml

# 2. Regenerate BOTH generators (they share the same source)
cd src/charts/syrf-common && pnpm run generate:env-blocks
cd src/services/web && pnpm run generate:flags

# 3. Review and commit all changes
git add -A
git commit -m "feat: add new config option"

Modifying dependency-map.yaml¶

When changing service dependencies:

# 1. Edit the source
vim docs/architecture/dependency-map.yaml

# 2. Regenerate Dockerfiles
python scripts/generate-dockerfiles.py

# 3. Review and commit
git add -A
git commit -m "chore: update service dependencies"

Modifying API Endpoints or DTOs¶

When changing API controllers, DTOs, or endpoints, building the API automatically regenerates both swagger.json and the TypeScript client:

# 1. Make API changes
vim src/services/api/SyRF.API.Endpoint/Controllers/...

# 2. Build API in Release mode — swagger.json, TypeScript client, and checksums are regenerated automatically
dotnet build src/services/api/SyRF.API.Endpoint -c Release

# 3. Review and commit
git add -A
git commit -m "feat(api): add new endpoint"

Automatic generation details:

The API .csproj has an AfterBuild target that runs NSwag spec generation followed by TypeScript client generation
Only runs on Release builds (-c Release) — Debug builds skip generation for faster iteration
TypeScript client generation requires pnpm install in src/services/web/ (warns and skips if missing)
Disable with dotnet build -c Release /p:GenerateOpenApi=false if you want a Release build without regeneration

Manual generation (if you need to run steps individually):

# Generate swagger.json only (from compiled API assembly)
cd src/services/web && pnpm run nswag:spec

# Generate TypeScript client only (from existing swagger.json)
cd src/services/web && pnpm run nswag:generate

# Generate both spec + client + checksums in one command
cd src/services/web && pnpm run nswag:all

Note: The swagger.json file is committed to the repository as the source of truth for the API client generation. This allows the TypeScript client to be regenerated without running the API.

If Precommit Fails¶

If you see a precommit failure like:

❌ Generated file validation failed!

Error: Source changed for "generate-env-blocks"
  Sources: src/charts/syrf-common/env-mapping.yaml
  Fix: cd src/charts/syrf-common && pnpm run generate:env-blocks

Follow the fix command shown, then stage and commit again:

# Run the suggested command
cd src/charts/syrf-common && pnpm run generate:env-blocks

# Stage the regenerated files
git add -A

# Commit again
git commit -m "your message"

Generated Files Reference¶

From env-mapping.yaml (generate-env-blocks)¶

File	Purpose
`src/charts/syrf-common/templates/_env-blocks.tpl`	Helm template for env vars
`src/services/web/src/assets/data/env.template.generated.json`	Runtime env template
`src/services/web/src/assets/data/appConfig.default.generated.json`	Default config values
`src/services/web/src/app/core/services/config/external-config.generated.ts`	External config interface
`src/services/web/src/app/core/services/config/app-config.generated.ts`	App config interface
`src/services/web/src/app/core/services/config/feature-flags.generated.ts`	Feature flags interface
`src/services/web/src/app/core/services/config/load-config.generated.ts`	Config loader function

From env-mapping.yaml (generate-feature-flags)¶

File	Purpose
`src/services/web/src/app/generated/feature-flags.constants.ts`	Flag defaults and mappings
`src/services/web/src/app/generated/feature-flags.types.ts`	TypeScript types
`src/services/web/src/app/generated/feature-flags.parser.ts`	Config parser
`src/services/web/src/app/generated/feature-flags.selectors.ts`	ngrx selectors

From dependency-map.yaml (generate-dockerfiles)¶

File	Purpose
`src/services/api/SyRF.API.Endpoint/Dockerfile`	API service Docker build
`src/services/project-management/SyRF.ProjectManagement.Endpoint/Dockerfile`	PM service Docker build
`src/services/quartz/SyRF.Quartz/Dockerfile`	Quartz service Docker build
`src/services/s3-notifier/SyRF.S3FileSavedNotifier.Endpoint/Dockerfile`	S3 Notifier Docker build
`src/services/web/Dockerfile`	Web frontend Docker build
`user-guide/Dockerfile`	User guide Docker build

From swagger.json (NSwag)¶

File	Purpose
`src/services/web/src/app/core/services/api-client.generated.ts`	TypeScript API client

Source files:

src/services/web/swagger.json - OpenAPI specification (generated from API assembly, committed to repo)
src/services/web/syrf-local.nswag - NSwag client generation config
src/services/web/syrf-generate-spec.nswag - NSwag spec generation from assembly

Troubleshooting¶

"Generator script changed" Warning¶

This is informational only. It means the generator script was modified but outputs haven't been regenerated. You can safely ignore this or regenerate to update the checksums.

Manual Edit Detected¶

If you see "Output file manually edited", it means someone edited a generated file directly. Run the appropriate generator to restore the correct content.

Missing Checksums Manifest¶

If .generated-checksums.json is missing:

pnpm exec tsx scripts/init-checksums.ts

This initializes the manifest with current file hashes.

CI Integration¶

The validation runs automatically on PRs when generated files or their sources are modified. The job is defined in .github/workflows/pr-tests.yml as validate-generated-code.

Architecture¶

┌──────────────────────┐
│  Source Files        │
│  - env-mapping.yaml  │
│  - dependency-map    │
│  - swagger.json      │
└─────────┬────────────┘
          │
          ▼
┌──────────────────────┐     ┌──────────────────────┐
│  Generator Scripts   │────▶│  Generated Files     │
│  - generate-*.ts     │     │  - *.generated.ts    │
│  - generate-*.py     │     │  - Dockerfiles       │
│  - NSwag             │     │  - api-client.ts     │
└─────────┬────────────┘     └──────────────────────┘
          │
          ▼
┌─────────────────────────────────────────┐
│  .generated-checksums.json              │
│  - sourceHash (detects source changes)  │
│  - outputHash (detects manual edits)    │
│  - generatorHash (informational)        │
└─────────────────────────────────────────┘
          │
          ▼
┌─────────────────────┐
│  Validation         │
│  - Precommit hook   │
│  - CI workflow      │
└─────────────────────┘