Convert topological sort utility to TypeScript

[EvanHahn]

no ref

This change should have no user impact.

[coderabbitai]

Walkthrough

This PR migrates the topological sort utility from JavaScript to TypeScript with generic typing support. The new implementation defines a TopologicalSortable interface and exports a generic topologicalSort<T> function that performs depth-first search ordering on objects with name and optional dependency properties. The consumer module (data-generator.js) is updated to import the function using named export syntax to match the new module's export shape.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Convert topological sort utility to TypeScript' clearly and concisely summarizes the main change: migrating a JavaScript utility to TypeScript.
Description check	✅ Passed	The description relates to the changeset by indicating it involves converting code to TypeScript with no user impact, which aligns with the PR's objective.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch convert-topological-sort-ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

ghost/core/core/server/data/seeders/utils/topological-sort.ts (2)

23-40: ⚖️ Poor tradeoff

Consider adding cycle detection.

The current DFS implementation silently handles cycles by returning early when a visited node is encountered (line 24-26). While this prevents infinite recursion, circular dependencies in the table schema would produce an ordering that cannot satisfy all constraints. Consider detecting cycles and throwing an error to catch configuration issues early.

For example, if table A depends on B and B depends on A, the algorithm will produce an ordering, but neither ordering [A, B] nor [B, A] satisfies both constraints.

🔍 Potential enhancement for cycle detection

Track nodes in the current DFS path separately from globally visited nodes:

 export function topologicalSort<T extends TopologicalSortable>(objects: ReadonlyArray<T>): T[] {
     const result: T[] = [];
     const visited = new Set<string>();
+    const visiting = new Set<string>();
     const objectsByName = new Map<string, T>();
 
     for (const object of objects) {
         objectsByName.set(object.name, object);
     }
 
     function dfs(name: string): void {
+        if (visiting.has(name)) {
+            throw new Error(`Circular dependency detected: ${name}`);
+        }
         if (visited.has(name)) {
             return;
         }
 
         const object = objectsByName.get(name);
         if (!object) {
             return;
         }
 
+        visiting.add(name);
         visited.add(name);
 
         for (const dependency of object.dependencies || []) {
             dfs(dependency);
         }
 
+        visiting.delete(name);
         result.push(object);
     }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ghost/core/core/server/data/seeders/utils/topological-sort.ts` around lines
23 - 40, The DFS currently uses visited to avoid infinite recursion but doesn't
detect cycles; update dfs(name: string) to maintain a separate "visiting" (or
"stack") Set in addition to visited so that when you encounter a dependency
already in visiting you throw a descriptive Error (include the cycle nodes)
instead of silently returning; use the existing symbols objectsByName,
object.dependencies, visited, result and ensure you remove the name from
visiting when unwinding so normal topological ordering still pushes object into
result.

---

28-31: ⚡ Quick win

Document or validate missing dependency behavior.

When a dependency name is declared but the corresponding object is not found in the input array, the function silently skips it (lines 28-31). This could hide configuration errors or typos in dependency declarations.

Consider either:

1. Documenting this behavior in the JSDoc if it's intentional (e.g., for external/optional dependencies), or
2. Throwing an error to fail fast on misconfiguration

📝 Example: Add validation

     const object = objectsByName.get(name);
     if (!object) {
+        throw new Error(`Dependency "${name}" not found in input objects`);
-        return;
     }

Or document the behavior:

 /**
  * This sorting algorithm is used to make sure that dependent tables are imported after their dependencies.
+ * 
+ * `@param` objects - Array of objects to sort. Each object must have a `name` and optional `dependencies` array.
+ * `@returns` Sorted array where dependencies appear before dependents. Missing dependencies are silently skipped.
  */

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ghost/core/core/server/data/seeders/utils/topological-sort.ts` around lines
28 - 31, The code currently silently skips missing dependencies at
objectsByName.get(name) (the local variable object) which can hide
misconfigurations; update the topological sort implementation (the function
containing objectsByName.get(name), e.g., the visit/resolve function in
topological-sort.ts) to validate that object exists and throw a clear error
including the missing dependency name (and ideally the parent object's
name/context) instead of returning silently; alternatively, if missing
dependencies are intentional, add a JSDoc comment on the topological sort
function explaining that missing names are ignored and why.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@ghost/core/core/server/data/seeders/utils/topological-sort.ts`:
- Around line 23-40: The DFS currently uses visited to avoid infinite recursion
but doesn't detect cycles; update dfs(name: string) to maintain a separate
"visiting" (or "stack") Set in addition to visited so that when you encounter a
dependency already in visiting you throw a descriptive Error (include the cycle
nodes) instead of silently returning; use the existing symbols objectsByName,
object.dependencies, visited, result and ensure you remove the name from
visiting when unwinding so normal topological ordering still pushes object into
result.
- Around line 28-31: The code currently silently skips missing dependencies at
objectsByName.get(name) (the local variable object) which can hide
misconfigurations; update the topological sort implementation (the function
containing objectsByName.get(name), e.g., the visit/resolve function in
topological-sort.ts) to validate that object exists and throw a clear error
including the missing dependency name (and ideally the parent object's
name/context) instead of returning silently; alternatively, if missing
dependencies are intentional, add a JSDoc comment on the topological sort
function explaining that missing names are ignored and why.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 80843f2e-87f6-4110-91b0-46341ab54ebe

📥 Commits

Reviewing files that changed from the base of the PR and between ebc1304 and b8ccc0b.

📒 Files selected for processing (3)

• ghost/core/core/server/data/seeders/data-generator.js
• ghost/core/core/server/data/seeders/utils/topological-sort.js
• ghost/core/core/server/data/seeders/utils/topological-sort.ts

💤 Files with no reviewable changes (1)

• ghost/core/core/server/data/seeders/utils/topological-sort.js