diff --git a/pkg/cli/dependency_graph_test.go b/pkg/cli/dependency_graph_test.go index acf9d5d7d80..548f70cf7de 100644 --- a/pkg/cli/dependency_graph_test.go +++ b/pkg/cli/dependency_graph_test.go @@ -8,6 +8,7 @@ import ( "path/filepath" "testing" + "github.com/github/gh-aw/pkg/parser" "github.com/github/gh-aw/pkg/workflow" ) @@ -764,3 +765,169 @@ imports: } }) } + +// TestDependencyGraph_TopologicalConsistencyContract is the cross-path contract test. +// +// It verifies that for the same set of fixture files the DependencyGraph import +// relationships (extracted via extractImportsFromFrontmatter) are consistent with +// the topological ordering produced by the import processor +// (parser.ProcessImportsFromFrontmatterWithManifest). +// +// Concretely: every dependency captured by the DependencyGraph must appear at a +// lower index in the import processor result than the file that depends on it. +// A regression to lexical sorting in the import processor would violate this +// contract for fixtures where dependency order conflicts with lexical filename order. +func TestDependencyGraph_TopologicalConsistencyContract(t *testing.T) { + tests := []struct { + name string + // files maps filename to frontmatter+content written into a temp dir. + files map[string]string + topImports []string // imports listed in the top-level workflow + }{ + { + // Lexical order (a < z) is the reverse of dependency order (z imports a). + name: "lexical order inverted: z-parent must follow a-child", + files: map[string]string{ + "z-parent.md": `--- +imports: + - a-child.md +tools: + tool-z: {} +---`, + "a-child.md": `--- +tools: + tool-a: {} +---`, + }, + topImports: []string{"z-parent.md"}, + }, + { + // Three-level chain where lexical order (a < b < c) is the reverse of + // topological order (c depends on b depends on a -> emit a, b, c). + name: "three-level chain: deepest leaf first", + files: map[string]string{ + "c-root.md": `--- +imports: + - b-mid.md +tools: + tool-c: {} +---`, + "b-mid.md": `--- +imports: + - a-leaf.md +tools: + tool-b: {} +---`, + "a-leaf.md": `--- +tools: + tool-a: {} +---`, + }, + topImports: []string{"c-root.md"}, + }, + { + // Diamond: two files both depend on a shared leaf. The shared leaf must + // appear before both dependents regardless of lexical order. + name: "diamond: shared leaf before both dependents", + files: map[string]string{ + "z-left.md": `--- +imports: + - a-shared.md +tools: + tool-z: {} +---`, + "y-right.md": `--- +imports: + - a-shared.md +tools: + tool-y: {} +---`, + "a-shared.md": `--- +tools: + tool-shared: {} +---`, + }, + topImports: []string{"z-left.md", "y-right.md"}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + tmpDir := t.TempDir() + workflowsDir := filepath.Join(tmpDir, ".github", "workflows") + if err := os.MkdirAll(workflowsDir, 0755); err != nil { + t.Fatal(err) + } + + // Write fixture files. + for name, content := range tt.files { + if err := os.WriteFile(filepath.Join(workflowsDir, name), []byte(content), 0600); err != nil { + t.Fatalf("writing fixture %s: %v", name, err) + } + } + + // --- Path 1: dependency graph --- + // Build the graph and collect the import relationships it captures. + graph := NewDependencyGraph(workflowsDir) + compiler := workflow.NewCompiler() + if err := graph.BuildGraph(compiler); err != nil { + t.Fatalf("BuildGraph() error = %v", err) + } + + // Gather absolute-path dependencies from the graph nodes. + absDepMap := make(map[string][]string, len(graph.nodes)) + for absPath, node := range graph.nodes { + absDepMap[absPath] = node.Imports + } + + // --- Path 2: import processor --- + // Run the import processor on the same top-level import list and collect + // the topologically sorted ImportedFiles (relative paths). + fm := map[string]any{"imports": tt.topImports} + result, err := parser.ProcessImportsFromFrontmatterWithManifest(fm, workflowsDir, nil) + if err != nil { + t.Fatalf("ProcessImportsFromFrontmatterWithManifest() error = %v", err) + } + importedFiles := result.ImportedFiles // relative paths + + // Build a position map for the import processor result. + pos := make(map[string]int, len(importedFiles)) + for i, f := range importedFiles { + pos[f] = i + } + + // --- Cross-path contract --- + // For every dependency relationship captured by the DependencyGraph, + // verify that the import processor result honours the topological + // constraint: the dependency must appear at a lower index than its importer. + for absImporter, absDeps := range absDepMap { + relImporter, err := filepath.Rel(workflowsDir, absImporter) + if err != nil { + continue + } + importerIdx, ok := pos[relImporter] + if !ok { + continue // file not in the import processor result; skip + } + for _, absDep := range absDeps { + relDep, err := filepath.Rel(workflowsDir, absDep) + if err != nil { + continue + } + depIdx, ok2 := pos[relDep] + if !ok2 { + continue + } + if depIdx >= importerIdx { + t.Errorf("cross-path contract violated: dependency graph says %q imports %q, "+ + "but import processor placed %q (pos %d) after %q (pos %d); "+ + "full order: %v", + relImporter, relDep, + relDep, depIdx, relImporter, importerIdx, + importedFiles) + } + } + } + }) + } +} diff --git a/pkg/parser/import_topological_contract_test.go b/pkg/parser/import_topological_contract_test.go new file mode 100644 index 00000000000..632d217ba54 --- /dev/null +++ b/pkg/parser/import_topological_contract_test.go @@ -0,0 +1,503 @@ +//go:build !integration + +// Package parser_test contains contract tests for topological import ordering. +// +// These tests lock in the guarantee that import ordering is always topological +// (dependency semantics: dependencies appear before their dependents) regardless +// of lexical filename ordering. +// +// Tie-break rule (documented contract): when multiple nodes are ready at the same +// time (in-degree 0 in Kahn's algorithm), they are ordered alphabetically by their +// relative filename. Tests that verify this rule use fixtures where the tie-break +// outcome differs from the declaration order. +// +// Cross-path contract: each fixture is verified via +// +// (1) the import processor path (ProcessImportsFromFrontmatterWithManifest), and +// (2) an independent dependency-map extracted directly from the fixture files, +// +// ensuring both representations agree on what constitutes a valid topological order. +package parser_test + +import ( + "os" + "path/filepath" + "testing" + + "github.com/github/gh-aw/pkg/parser" + "github.com/github/gh-aw/pkg/testutil" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// verifyTopologicalConstraints asserts the core topological property: +// for every (importer, dep) pair where dep is listed as a dependency of importer, +// dep must appear at a strictly lower index than importer in result. +// +// deps maps a relative filename to the set of relative filenames it directly imports +// (matching the format stored in result, e.g. "b.md" not "b.md#Section"). +// Files absent from result are silently skipped (they may be filtered out). +func verifyTopologicalConstraints(t *testing.T, result []string, deps map[string][]string) { + t.Helper() + + pos := make(map[string]int, len(result)) + for i, f := range result { + pos[f] = i + } + + for importer, imports := range deps { + importerIdx, ok := pos[importer] + if !ok { + continue + } + for _, dep := range imports { + depIdx, ok2 := pos[dep] + if !ok2 { + continue + } + assert.Less(t, depIdx, importerIdx, + "topological constraint violated: %q (pos %d) must appear before %q (pos %d) because %q depends on %q", + dep, depIdx, importer, importerIdx, importer, dep) + } + } +} + +// buildDepMapFromFiles reads each file in the given directory and returns a map +// of relative filename → list of relative filenames it imports. Section suffixes +// (e.g. "#Tools") are stripped from dependency values to match the flat filenames +// used as keys in result. +func buildDepMapFromFiles(t *testing.T, dir string, files map[string]string) map[string][]string { + t.Helper() + + depMap := make(map[string][]string, len(files)) + for filename, content := range files { + fm, err := parser.ExtractFrontmatterFromContent(content) + require.NoError(t, err, "parsing frontmatter for %s", filename) + + var deps []string + if importsRaw, ok := fm.Frontmatter["imports"]; ok { + switch v := importsRaw.(type) { + case []any: + for _, item := range v { + switch iv := item.(type) { + case string: + base := iv + if idx := indexOf(iv, "#"); idx != -1 { + base = iv[:idx] + } + deps = append(deps, base) + case map[string]any: + if p, ok2 := iv["path"].(string); ok2 { + base := p + if idx := indexOf(p, "#"); idx != -1 { + base = p[:idx] + } + deps = append(deps, base) + } + } + } + case []string: + for _, iv := range v { + base := iv + if idx := indexOf(iv, "#"); idx != -1 { + base = iv[:idx] + } + deps = append(deps, base) + } + } + } + depMap[filename] = deps + } + return depMap +} + +// indexOf returns the index of the first occurrence of sub in s, or -1 if not found. +func indexOf(s, sub string) int { + for i := 0; i <= len(s)-len(sub); i++ { + if s[i:i+len(sub)] == sub { + return i + } + } + return -1 +} + +// writeFiles creates all entries of the files map as real files under dir. +func writeFiles(t *testing.T, dir string, files map[string]string) { + t.Helper() + for name, content := range files { + path := filepath.Join(dir, name) + require.NoError(t, os.WriteFile(path, []byte(content), 0600), + "writing fixture file %s", name) + } +} + +// runImportProcessor processes the given top-level import list via +// ProcessImportsFromFrontmatterWithManifest and returns the ImportedFiles slice. +func runImportProcessor(t *testing.T, dir string, topImports []string) []string { + t.Helper() + fm := map[string]any{"imports": topImports} + result, err := parser.ProcessImportsFromFrontmatterWithManifest(fm, dir, nil) + require.NoError(t, err, "ProcessImportsFromFrontmatterWithManifest must not fail") + return result.ImportedFiles +} + +// --------------------------------------------------------------------------- +// TestImportTopologicalContractLexicalConflict +// --------------------------------------------------------------------------- + +// TestImportTopologicalContractLexicalConflict verifies that when dependency order +// conflicts with lexical filename order the output remains topological. +// +// Each sub-test is designed so that a naive lexical sort would produce wrong +// results (placing a dependent before its dependency). The test therefore acts +// as an explicit regression lock: it will fail the moment the implementation +// regresses to lexical ordering. +func TestImportTopologicalContractLexicalConflict(t *testing.T) { + tests := []struct { + name string + files map[string]string + topImports []string + // deps mirrors the logical dependency relationships declared in the files. + // Used by verifyTopologicalConstraints (independent of expected order). + deps map[string][]string + // wantOrder is the expected deterministic output, useful as a documentation + // anchor for the tie-break rule. The property check via deps is authoritative. + wantOrder []string + }{ + { + // "z-uses-a" would be wrong under lexical sort (a < z, but z imports a → + // a must come first). + name: "z-parent imports a-child: dependency beats lexical order", + files: map[string]string{ + "z-parent.md": `--- +imports: + - a-child.md +tools: + tool-z: {} +---`, + "a-child.md": `--- +tools: + tool-a: {} +---`, + }, + topImports: []string{"z-parent.md"}, + deps: map[string][]string{ + "z-parent.md": {"a-child.md"}, + "a-child.md": {}, + }, + wantOrder: []string{"a-child.md", "z-parent.md"}, + }, + { + // Reversed three-node chain: lexical order (a < b < c) would be wrong + // because c imports b which imports a, so correct order is a, b, c. + name: "chain c→b→a: leaves must precede internal nodes precede roots", + files: map[string]string{ + "c-root.md": `--- +imports: + - b-mid.md +tools: + tool-c: {} +---`, + "b-mid.md": `--- +imports: + - a-leaf.md +tools: + tool-b: {} +---`, + "a-leaf.md": `--- +tools: + tool-a: {} +---`, + }, + topImports: []string{"c-root.md"}, + deps: map[string][]string{ + "c-root.md": {"b-mid.md"}, + "b-mid.md": {"a-leaf.md"}, + "a-leaf.md": {}, + }, + wantOrder: []string{"a-leaf.md", "b-mid.md", "c-root.md"}, + }, + { + // Two-branch tree where each branch's leaf has a lexically later name than + // its parent. Lexical sort would interleave parents before leaves. + name: "two branches with lexically-later leaves", + files: map[string]string{ + "a-parent.md": `--- +imports: + - z-leaf-a.md +tools: + tool-a-parent: {} +---`, + "b-parent.md": `--- +imports: + - y-leaf-b.md +tools: + tool-b-parent: {} +---`, + "z-leaf-a.md": `--- +tools: + tool-z: {} +---`, + "y-leaf-b.md": `--- +tools: + tool-y: {} +---`, + }, + topImports: []string{"a-parent.md", "b-parent.md"}, + deps: map[string][]string{ + "a-parent.md": {"z-leaf-a.md"}, + "b-parent.md": {"y-leaf-b.md"}, + "z-leaf-a.md": {}, + "y-leaf-b.md": {}, + }, + // Kahn's algorithm: queue is sorted globally after each emit. + // y-leaf-b.md is emitted first (y < z alphabetically). That immediately + // makes b-parent.md ready; after sorting, the queue becomes + // [b-parent.md, z-leaf-a.md] (b < z), so b-parent.md is emitted next. + // Then z-leaf-a.md is emitted, making a-parent.md ready. + // Key invariant: every leaf precedes its own parent (topological guarantee). + wantOrder: []string{"y-leaf-b.md", "b-parent.md", "z-leaf-a.md", "a-parent.md"}, + }, + { + // Diamond: two parents share the same leaf. Lexical sort would not + // guarantee the leaf precedes both parents. + name: "diamond: shared leaf must precede both parents", + files: map[string]string{ + "z-left.md": `--- +imports: + - a-base.md +tools: + tool-z-left: {} +---`, + "y-right.md": `--- +imports: + - a-base.md +tools: + tool-y-right: {} +---`, + "a-base.md": `--- +tools: + tool-a-base: {} +---`, + }, + topImports: []string{"z-left.md", "y-right.md"}, + deps: map[string][]string{ + "z-left.md": {"a-base.md"}, + "y-right.md": {"a-base.md"}, + "a-base.md": {}, + }, + wantOrder: []string{"a-base.md", "y-right.md", "z-left.md"}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + dir := testutil.TempDir(t, "contract-lexical-*") + writeFiles(t, dir, tt.files) + + got := runImportProcessor(t, dir, tt.topImports) + + // 1. Property check (authoritative): every dependency must come before + // its importer in the output. + verifyTopologicalConstraints(t, got, tt.deps) + + // 2. Exact-order check: documents the deterministic tie-break behaviour. + assert.Equal(t, tt.wantOrder, got, + "import processor output must match documented deterministic order") + }) + } +} + +// --------------------------------------------------------------------------- +// TestImportTopologicalContractTieBreakIsAlphabetical +// --------------------------------------------------------------------------- + +// TestImportTopologicalContractTieBreakIsAlphabetical explicitly documents and +// verifies the tie-break rule: when multiple nodes are simultaneously ready +// (in-degree 0 in Kahn's algorithm), they are sorted alphabetically by their +// relative filename. +// +// This test uses fixtures where all nodes are roots (no dependencies), so the +// only ordering constraint is the tie-break rule itself. +func TestImportTopologicalContractTieBreakIsAlphabetical(t *testing.T) { + t.Run("all-roots ordered alphabetically regardless of declaration order", func(t *testing.T) { + files := map[string]string{ + "omega.md": "---\ntools:\n t: {}\n---", + "alpha.md": "---\ntools:\n t: {}\n---", + "gamma.md": "---\ntools:\n t: {}\n---", + "beta.md": "---\ntools:\n t: {}\n---", + } + // Declaration order is deliberately not alphabetical. + topImports := []string{"omega.md", "alpha.md", "gamma.md", "beta.md"} + + dir := testutil.TempDir(t, "contract-tiebreak-*") + writeFiles(t, dir, files) + + got := runImportProcessor(t, dir, topImports) + + require.Len(t, got, 4, "all four files must appear in the result") + // Tie-break rule: alphabetical by filename. + assert.Equal(t, []string{"alpha.md", "beta.md", "gamma.md", "omega.md"}, got, + "independent nodes must be sorted alphabetically (documented tie-break rule)") + }) + + t.Run("ready nodes at each wave are alphabetically sorted", func(t *testing.T) { + // Build a two-wave structure: first wave (leaves) has {z-leaf, a-leaf}, + // second wave (parents) has {c-parent, b-parent}. + // Within each wave, alphabetical order must apply. + files := map[string]string{ + "c-parent.md": `--- +imports: + - z-leaf.md +tools: + tool-c: {} +---`, + "b-parent.md": `--- +imports: + - a-leaf.md +tools: + tool-b: {} +---`, + "z-leaf.md": "---\ntools:\n tz: {}\n---", + "a-leaf.md": "---\ntools:\n ta: {}\n---", + } + topImports := []string{"c-parent.md", "b-parent.md"} + + dir := testutil.TempDir(t, "contract-tiebreak-wave-*") + writeFiles(t, dir, files) + + got := runImportProcessor(t, dir, topImports) + + require.Len(t, got, 4) + // Wave 1 (leaves): a-leaf < z-leaf alphabetically. + // Wave 2 (parents become ready after their respective leaf): b-parent + // and c-parent become ready at different points because each parent + // depends only on its own leaf. + // After a-leaf is emitted, b-parent (in-degree drops to 0) is queued. + // After z-leaf is emitted, c-parent (in-degree drops to 0) is queued. + assert.Equal(t, []string{"a-leaf.md", "b-parent.md", "z-leaf.md", "c-parent.md"}, got, + "within each Kahn wave, nodes must be sorted alphabetically") + + // Property check: no dependency constraint violated. + verifyTopologicalConstraints(t, got, map[string][]string{ + "c-parent.md": {"z-leaf.md"}, + "b-parent.md": {"a-leaf.md"}, + }) + }) +} + +// --------------------------------------------------------------------------- +// TestImportTopologicalContractCrossPath +// --------------------------------------------------------------------------- + +// TestImportTopologicalContractCrossPath is the cross-path contract test. +// +// It verifies that for the same set of fixture files: +// +// 1. The import processor path (ProcessImportsFromFrontmatterWithManifest) produces +// a valid topological ordering of ImportedFiles. +// 2. An independently extracted dependency map (built directly from the raw +// frontmatter without invoking the import processor) agrees with the ordering +// produced by (1). +// +// This separates the ordering-producer (import processor) from the +// ordering-verifier (dependency extractor), so a regression in either code path +// will surface as a test failure. +func TestImportTopologicalContractCrossPath(t *testing.T) { + tests := []struct { + name string + files map[string]string + topImports []string + }{ + { + name: "linear chain: lexical reverse of topological", + files: map[string]string{ + "z-top.md": `--- +imports: + - m-mid.md +tools: + tool-z: {} +---`, + "m-mid.md": `--- +imports: + - a-bot.md +tools: + tool-m: {} +---`, + "a-bot.md": `--- +tools: + tool-a: {} +---`, + }, + topImports: []string{"z-top.md"}, + }, + { + name: "diamond: shared dependency", + files: map[string]string{ + "z-a.md": `--- +imports: + - a-shared.md +tools: + tool-za: {} +---`, + "z-b.md": `--- +imports: + - a-shared.md +tools: + tool-zb: {} +---`, + "a-shared.md": `--- +tools: + tool-shared: {} +---`, + }, + topImports: []string{"z-a.md", "z-b.md"}, + }, + { + name: "wide: many independent branches", + files: map[string]string{ + "c-root.md": `--- +imports: + - z-leaf.md +tools: + tool-c: {} +---`, + "b-root.md": `--- +imports: + - y-leaf.md +tools: + tool-b: {} +---`, + "a-root.md": `--- +imports: + - x-leaf.md +tools: + tool-a: {} +---`, + "z-leaf.md": "---\ntools:\n tz: {}\n---", + "y-leaf.md": "---\ntools:\n ty: {}\n---", + "x-leaf.md": "---\ntools:\n tx: {}\n---", + }, + topImports: []string{"c-root.md", "b-root.md", "a-root.md"}, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + dir := testutil.TempDir(t, "contract-crosspath-*") + writeFiles(t, dir, tt.files) + + // Path 1: import processor produces the ordering. + got := runImportProcessor(t, dir, tt.topImports) + + // Path 2: independently extract the dependency map from raw frontmatter. + depMap := buildDepMapFromFiles(t, dir, tt.files) + + // Cross-path contract: the ordering from path 1 must satisfy the + // constraints captured by path 2. + verifyTopologicalConstraints(t, got, depMap) + + t.Logf("cross-path verified: import processor order = %v", got) + }) + } +} diff --git a/pkg/workflow/data/action_pins.json b/pkg/workflow/data/action_pins.json index 8ea5eab0fc6..29175c8b149 100644 --- a/pkg/workflow/data/action_pins.json +++ b/pkg/workflow/data/action_pins.json @@ -160,11 +160,6 @@ "version": "v3.32.3", "sha": "17ec405481c24be464d4b2c5727a82f700ddb189" }, - "github/stale-repos@v3": { - "repo": "github/stale-repos", - "version": "v3", - "sha": "3477b6488008d9411aaf22a0924ec7c1f6a69980" - }, "github/stale-repos@v3.0.2": { "repo": "github/stale-repos", "version": "v3.0.2", @@ -185,11 +180,6 @@ "version": "v1.288.0", "sha": "09a7688d3b55cf0e976497ff046b70949eeaccfd" }, - "super-linter/super-linter@v8.2.1": { - "repo": "super-linter/super-linter", - "version": "v8.2.1", - "sha": "2bdd90ed3262e023ac84bf8fe35dc480721fc1f2" - }, "super-linter/super-linter@v8.5.0": { "repo": "super-linter/super-linter", "version": "v8.5.0",