feat: add template dependency ordering via @depends-on comments (#61)

#### In This PR

Templates can now declare explicit dependencies on other templates using
`@depends-on` comments:

```sql
-- @depends-on: helper_functions.sql, base_types.sql
CREATE FUNCTION complex_calc() ...
```

During `apply` and `build`, templates are topologically sorted so
dependencies run first. Circular dependencies are detected and reported
as warnings (execution continues with best-effort ordering).

#### The Approach

Originally this branch attempted automatic SQL parsing - extracting
`CREATE TABLE/VIEW/FUNCTION` declarations and detecting `FROM`, `JOIN`,
`REFERENCES` clauses. After review feedback, this was simplified to
explicit `@depends-on` comments. The tradeoffs:

- **Explicit > implicit**: Users know exactly what's happening
- **No false positives**: SQL parsing can't reliably detect all
dependency types (CTEs, dynamic SQL, partial names)
- **Simpler implementation**: ~180 lines of focused code vs regex soup
- **Opt-in granularity**: Only declare dependencies where order matters

#### What Changed

- `dependencyParser.ts` - extracts `@depends-on` comments
(case-insensitive, deduped)
- `dependencyGraph.ts` - builds graph, topological sort, cycle detection
- `Orchestrator.ts` - integrates sorting into `apply()` and `build()`
- `--no-deps` flag on both commands to disable if needed
- Does NOT apply to `watch` (file-at-a-time execution)

#### Refs

Closes TT-XXX

Author: t1mmen

.changeset/smart-dependencies.md

@@ -0,0 +1,24 @@
+---
+"@t1mmen/srtd": minor
+---
+
+Add dependency ordering for SQL templates via @depends-on comments
+
+Templates can now declare dependencies on other templates using comments:
+
+```sql
+-- @depends-on: users_table.sql, roles.sql
+CREATE VIEW active_users AS ...
+```
+
+Features:
+- Templates sorted so dependencies apply/build first
+- Circular dependencies detected and reported
+- Case-insensitive filename matching
+- Multiple @depends-on comments supported
+
+Use `--no-deps` flag to disable if needed:
+```bash
+srtd apply --no-deps
+srtd build --no-deps
+```

README.md

@@ -133,6 +133,18 @@ my_experiment.wip.sql  → Applies locally, never builds to migration
 When it's ready: `srtd promote my_experiment.wip.sql`
 
 
+## Template Dependencies
+
+Declare dependencies between templates with `@depends-on` comments:
+
+```sql
+-- @depends-on: helper_functions.sql
+CREATE FUNCTION complex_calc() ...
+```
+
+During `apply` and `build`, templates are sorted so dependencies run first. Circular dependencies are detected and reported. Use `--no-deps` to disable.
+
+
 ## Existing Projects
 
 Already have functions in your database? Create templates for them, then:

src/__tests__/apply.test.ts

@@ -89,6 +89,7 @@ describe('Apply Command', () => {
     expect(mockOrchestrator.apply).toHaveBeenCalledWith({
       force: undefined,
       silent: true,
+      respectDependencies: true,
     });
     expect(spies.exitSpy).toHaveBeenCalledWith(0);
   });
@@ -109,6 +110,7 @@ describe('Apply Command', () => {
     expect(mockOrchestrator.apply).toHaveBeenCalledWith({
       force: true,
       silent: true,
+      respectDependencies: true,
     });
   });
 

src/__tests__/build.test.ts

@@ -105,6 +105,7 @@ describe('Build Command', () => {
       force: undefined,
       bundle: undefined,
       silent: true,
+      respectDependencies: true,
     });
     expect(spies.exitSpy).toHaveBeenCalledWith(0);
   });
@@ -126,6 +127,7 @@ describe('Build Command', () => {
       force: true,
       bundle: undefined,
       silent: true,
+      respectDependencies: true,
     });
   });
 
@@ -146,6 +148,7 @@ describe('Build Command', () => {
       force: undefined,
       bundle: true,
       silent: true,
+      respectDependencies: true,
     });
   });
 

src/commands/apply.ts

@@ -19,7 +19,8 @@ import { getErrorMessage } from '../utils/getErrorMessage.js';
 export const applyCommand = new Command('apply')
   .description('Apply built migrations to the database')
   .option('-f, --force', 'Force apply of all templates, irrespective of changes')
-  .action(async (options: { force?: boolean }) => {
+  .option('--no-deps', 'Disable automatic dependency ordering')
+  .action(async (options: { force?: boolean; deps?: boolean }) => {
     let exitCode = 0;
 
     try {
@@ -45,6 +46,7 @@ export const applyCommand = new Command('apply')
       const result: ProcessedTemplateResult = await orchestrator.apply({
         force: options.force,
         silent: true,
+        respectDependencies: options.deps,
       });
 
       // Transform results to unified TemplateResult format

src/commands/build.ts

@@ -21,13 +21,15 @@ interface BuildOptions {
   force?: boolean;
   apply?: boolean;
   bundle?: boolean;
+  deps?: boolean;
 }
 
 export const buildCommand = new Command('build')
   .description('Build migrations from templates')
   .option('-f, --force', 'Force building of all templates, irrespective of changes')
   .option('-a, --apply', 'Apply the built templates')
   .option('-b, --bundle', 'Bundle all templates into a single migration')
+  .option('--no-deps', 'Disable automatic dependency ordering')
   .action(async (options: BuildOptions) => {
     let exitCode = 0;
 
@@ -56,6 +58,7 @@ export const buildCommand = new Command('build')
         force: options.force,
         bundle: options.bundle,
         silent: true,
+        respectDependencies: options.deps,
       });
 
       let result = buildResult;

src/services/Orchestrator.ts

@@ -7,6 +7,7 @@
 import EventEmitter from 'node:events';
 import path from 'node:path';
 import type { CLIConfig, ProcessedTemplateResult, TemplateStatus } from '../types.js';
+import { buildDependencyGraph, detectCycles, topologicalSort } from '../utils/dependencyGraph.js';
 import { isWipTemplate } from '../utils/isWipTemplate.js';
 import type { ValidationWarning } from '../utils/schemas.js';
 import { DatabaseService } from './DatabaseService.js';
@@ -33,13 +34,17 @@ export interface ApplyOptions {
   force?: boolean;
   templatePaths?: string[];
   silent?: boolean;
+  /** Sort templates by dependencies before processing (default: true) */
+  respectDependencies?: boolean;
 }
 
 export interface BuildOptions {
   force?: boolean;
   bundle?: boolean;
   templatePaths?: string[];
   silent?: boolean;
+  /** Sort templates by dependencies before processing (default: true) */
+  respectDependencies?: boolean;
 }
 
 export interface WatchOptions {
@@ -428,9 +433,14 @@ export class Orchestrator extends EventEmitter implements Disposable {
    * Command handler: Apply templates to database
    */
   async apply(options: ApplyOptions = {}): Promise<ProcessedTemplateResult> {
-    const templates = options.templatePaths || (await this.fileSystemService.findTemplates());
+    let templates = options.templatePaths || (await this.fileSystemService.findTemplates());
     const result: ProcessedTemplateResult = { errors: [], applied: [], built: [], skipped: [] };
 
+    // Sort templates by dependencies (default: true)
+    if (options.respectDependencies !== false) {
+      templates = await this.sortByDependencies(templates);
+    }
+
     this.log('\\n');
     const action = options.force ? 'Force applying' : 'Applying';
     this.log(`${action} changed templates to local database...`, 'success');
@@ -474,7 +484,12 @@ export class Orchestrator extends EventEmitter implements Disposable {
    * Command handler: Build migration files from templates
    */
   async build(options: BuildOptions = {}): Promise<ProcessedTemplateResult> {
-    const templates = options.templatePaths || (await this.fileSystemService.findTemplates());
+    let templates = options.templatePaths || (await this.fileSystemService.findTemplates());
+
+    // Sort templates by dependencies (default: true)
+    if (options.respectDependencies !== false) {
+      templates = await this.sortByDependencies(templates);
+    }
 
     this.log('\\n');
 
@@ -821,6 +836,50 @@ export class Orchestrator extends EventEmitter implements Disposable {
     return this.stateService.getRecentActivity(limit);
   }
 
+  /**
+   * Sort templates by their SQL dependencies
+   * Reads all templates, builds a dependency graph, and returns topologically sorted paths
+   */
+  private async sortByDependencies(templatePaths: string[]): Promise<string[]> {
+    if (templatePaths.length <= 1) {
+      return templatePaths;
+    }
+
+    // Read all templates in parallel to analyze dependencies
+    const templates = await Promise.all(
+      templatePaths.map(async templatePath => {
+        try {
+          const file = await this.fileSystemService.readTemplate(templatePath);
+          return { path: templatePath, content: file.content };
+        } catch (error) {
+          // Log warning but include with empty content so it still appears in sorted output
+          const fileName = path.basename(templatePath);
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          this.log(`Warning: Could not read ${fileName}: ${errorMsg}`, 'warn');
+          return { path: templatePath, content: '' };
+        }
+      })
+    );
+
+    // Build dependency graph and detect cycles
+    const graph = buildDependencyGraph(templates);
+    const cycles = detectCycles(graph);
+
+    // Warn about circular dependencies
+    if (cycles.length > 0) {
+      this.log('Warning: Circular dependencies detected:', 'warn');
+      for (const cycle of cycles) {
+        const firstNode = cycle[0];
+        if (!firstNode) continue;
+        const cycleStr = [...cycle, firstNode].map(p => path.basename(p)).join(' → ');
+        this.log(`  ${cycleStr}`, 'warn');
+      }
+    }
+
+    // Return topologically sorted templates
+    return topologicalSort(graph);
+  }
+
   /**
    * Logging utility
    */