// Files: kebab-case
// contained-in-section.ts, code-frontmatter.ts

// Types/Interfaces: PascalCase
interface GraphEdge { ... }
type ExecutableTask = ...

// Functions/Variables: camelCase
function buildGraph() { ... }
const taskRunner = ...

// Constants: UPPER_SNAKE_CASE or camelCase
const DEFAULT_TIMEOUT = 120;
const typicalRules = [...];

// Explicit return types for public functions
function parseCell(code: Code): ParsedCell {
  // ...
}

// Infer types for local variables
const result = parseCell(node);

// Use unknown instead of any
function processUnknown(value: unknown): void {
  if (typeof value === "string") {
    // Type narrowing
  }
}

// 1. Standard library
import { join } from "std/path/mod.ts";

// 2. External dependencies
import { unified } from "unified";
import { visit } from "unist-util-visit";

// 3. Internal absolute imports
import { graph } from "@spry/axiom/graph.ts";

// 4. Relative imports
import { helper } from "./helper.ts";
import type { MyType } from "./types.ts";

// 1. Imports
import { ... } from "...";

// 2. Types/Interfaces
export interface MyInterface { ... }
export type MyType = ...;

// 3. Constants
const DEFAULT_VALUE = 42;

// 4. Helper functions (private)
function helperFunction() { ... }

// 5. Main exports (public)
export function mainFunction() { ... }
export class MainClass { ... }

// Good: Small, focused functions
function validateTask(task: Task): ValidationResult {
  const errors = [];
  if (!task.taskId()) errors.push("Missing task ID");
  if (task.taskDeps()?.some(d => !isValidId(d))) {
    errors.push("Invalid dependency");
  }
  return { valid: errors.length === 0, errors };
}

type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

function parseConfig(content: string): Result<Config, ParseError> {
  try {
    const parsed = JSON.parse(content);
    return { ok: true, value: parsed as Config };
  } catch (e) {
    return { ok: false, error: new ParseError(e.message) };
  }
}

// Programming errors
function assertNever(value: never): never {
  throw new Error(`Unexpected value: ${value}`);
}

// Input validation at boundaries
function processFile(path: string): void {
  if (!path) throw new Error("Path is required");
  // ...
}

import { assertEquals, assertThrows } from "@std/assert";

Deno.test("executionPlan creates valid topological order", () => {
  // Arrange
  const tasks = createTestTasks();

  // Act
  const plan = executionPlan(tasks);

  // Assert
  assertEquals(plan.layers.length, 3);
  assertEquals(plan.dag.length, tasks.length);
});

Deno.test("executionPlan throws on circular dependencies", () => {
  const circularTasks = createCircularTasks();
  
  assertThrows(
    () => executionPlan(circularTasks),
    Error,
    "Circular dependency detected"
  );
});

Deno.test("TaskExecutor", async (t) => {
  await t.step("executes single task", () => {
    // Test implementation
  });

  await t.step("handles dependencies", () => {
    // Test implementation
  });

  await t.step("reports failures", () => {
    // Test implementation
  });
});

# Run all tests
deno test --parallel --allow-all

# Format code
deno fmt

# Lint code
deno lint

/**
 * Builds a semantic graph from an MDAST root.
 *
 * @param root - The MDAST root node
 * @param rules - Edge rules to apply
 * @returns A graph with discovered relationships
 *
 * @example
 * ```ts
 * const g = graph(root, typicalRules());
 * console.log(g.edges.length);
 * ```
 */
export function graph(
  root: Root,
  rules: EdgeRule[]
): Graph {
  // ...
}

// Good: Lazy evaluation
function* findMatches(nodes: Node[]): Generator<Node> {
  for (const node of nodes) {
    if (matches(node)) yield node;
  }
}

// Use when needed
for (const match of findMatches(largeArray)) {
  // Process one at a time
}

// Better: Lazy evaluate when appropriate
function* getIds(tasks: Task[]): Generator<string> {
  for (const task of tasks) {
    yield task.taskId();
  }
}

<type>(<scope>): <description>

[optional body]

[optional footer]

feat(axiom): add custom edge rule support
fix(runbook): resolve dependency cycle detection
docs: improve contributing guide clarity

## What does this change?
Brief description of the changes

## Why is this needed?
Explain the motivation and use case

## How was it tested?
- [ ] Unit tests added/updated
- [ ] Manual testing performed
- [ ] Documentation updated

## Breaking changes?
None / List any breaking changes

## Related issues
Closes #123

lib/axiom/projection/
├── flexible.ts          # Main implementation
├── flexible_test.ts     # Tests
├── playbook.ts
├── playbook_test.ts
└── fixture/             # Test fixtures
    ├── sample.md
    └── complex.md