project

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 26, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package project is the Stage-1 namespace for project analysis, snapshots, impact analysis, dep updates, migrations, releases. See ../REFACTOR_PLAN.md.

Index

Constants

View Source 
const DefaultProjectSnapshotTTL = 10 * time.Second

DefaultProjectSnapshotTTL is the default time-to-live for a cached project snapshot.

Variables

View Source 
var ProjectContextFiles = []string{
	".hawk/project-context.md",
	".hawk/conventions.md",
	".hawk/architecture.md",
	".hawk/debt.md",
}

ProjectContextFiles are the files hawk auto-loads for project context.

Functions

func BuildImportGraph 

func BuildImportGraph(projectDir string) map[string][]string

BuildImportGraph parses Go source files to build a reverse dependency graph. Package A imports B means B's map entry includes A.

func BumpVersion 

func BumpVersion(current string, changes []ChangeEntry) string

BumpVersion determines the next version based on the changes. Breaking changes cause a major bump, features cause a minor bump, and fixes/other changes cause a patch bump.

func ClassifyUpdate 

func ClassifyUpdate(current, latest string) string

ClassifyUpdate compares two semver strings and returns "major", "minor", or "patch".

func DetectArchitecture 

func DetectArchitecture(dir string) string

DetectArchitecture determines the architectural style of a project by examining its directory structure.

func FormatAnalysis 

func FormatAnalysis(analysis *ProjectAnalysis) string

FormatAnalysis produces a concise summary string from a ProjectAnalysis.

func FormatImpact 

func FormatImpact(analysis *ImpactAnalysis) string

FormatImpact produces a human-readable formatted report of the impact analysis.

func FormatOutdated 

func FormatOutdated(deps []Dependency) string

FormatOutdated formats a list of outdated dependencies into a human-readable report.

func FormatPlan 

func FormatPlan(plan *UpdatePlan) string

FormatPlan formats an UpdatePlan into a human-readable string.

func FormatReleaseNotes 

func FormatReleaseNotes(release *Release) string

FormatReleaseNotes produces GitHub-style release notes with sections.

func FormatViolations 

func FormatViolations(violations []Violation) string

FormatViolations formats a list of violations for display.

func GenerateChangelog 

func GenerateChangelog(release *Release) string

GenerateChangelog produces a markdown-formatted changelog for a release.

func GenerateOnboardingDoc 

func GenerateOnboardingDoc(analysis *ProjectAnalysis) string

GenerateOnboardingDoc produces a human-readable onboarding document from the analysis.

func ParseSemver 

func ParseSemver(version string) (major, minor, patch int, err error)

ParseSemver parses a version string into major, minor, patch components. It handles versions with or without a "v" prefix.

func UpdateVersionFile 

func UpdateVersionFile(version, filePath string) error

UpdateVersionFile updates the version string in the given file. Supports Go constant files, package.json, and Cargo.toml formats.

Types

type ChangeEntry 

type ChangeEntry struct {
	Type        string // "feat", "fix", "refactor", "perf", "docs", "test", "chore"
	Scope       string
	Description string
	CommitHash  string
	Author      string
	Breaking    bool
}

ChangeEntry represents a single change parsed from a commit message.

func ParseConventionalCommit 

func ParseConventionalCommit(msg string) *ChangeEntry

ParseConventionalCommit parses a commit message in conventional commit format. Returns nil if the message cannot be parsed.

type Convention 

type Convention struct {
	Name        string
	Description string
	Pattern     *regexp.Regexp
	AntiPattern *regexp.Regexp
	Language    string
	Category    string // "naming", "structure", "error_handling", "testing", "style"
	Example     string
	Confidence  float64 // 0.0 to 1.0 — how confident we are this convention applies
}

Convention represents a single coding convention that can be enforced on generated code.

type ConventionSet 

type ConventionSet struct {
	Conventions []Convention
	ProjectDir  string
	// contains filtered or unexported fields
}

ConventionSet holds a collection of conventions learned from a project.

func NewConventionSet 

func NewConventionSet(projectDir string) *ConventionSet

NewConventionSet creates a new ConventionSet for the given project directory.

func (*ConventionSet) AddConvention 

func (cs *ConventionSet) AddConvention(conv Convention)

AddConvention adds a new convention to the set.

func (*ConventionSet) Check 

func (cs *ConventionSet) Check(code, file string) []Violation

Check validates generated code against all learned conventions and returns violations.

func (*ConventionSet) CheckErrorHandling 

func (cs *ConventionSet) CheckErrorHandling(code string) []Violation

CheckErrorHandling verifies error handling matches the project's style.

func (*ConventionSet) CheckNaming 

func (cs *ConventionSet) CheckNaming(code string) []Violation

CheckNaming verifies names follow the project's naming conventions.

func (*ConventionSet) CheckTestStyle 

func (cs *ConventionSet) CheckTestStyle(code string) []Violation

CheckTestStyle verifies tests match the project's testing patterns.

func (*ConventionSet) Enforce 

func (cs *ConventionSet) Enforce(code string) (string, []Violation)

Enforce auto-fixes violations where possible and returns fixed code plus remaining violations.

func (*ConventionSet) FormatConventions 

func (cs *ConventionSet) FormatConventions() string

FormatConventions lists all learned conventions in a human-readable format.

func (*ConventionSet) LearnConventions 

func (cs *ConventionSet) LearnConventions(projectDir string) error

LearnConventions scans existing code in projectDir to infer conventions: naming style, error handling, testing patterns, structure, and imports.

type Dependency 

type Dependency struct {
	Name               string
	CurrentVersion     string
	LatestVersion      string
	UpdateType         string // "major", "minor", "patch"
	IsDirectDep        bool
	HasBreakingChanges bool
	SecurityFix        bool
	Changelog          string
}

Dependency represents a single package dependency with version info.

type DependencyUpdater 

type DependencyUpdater struct {
	ProjectDir string
	Language   string
	// contains filtered or unexported fields
}

DependencyUpdater detects outdated packages and helps update them safely.

func NewDependencyUpdater 

func NewDependencyUpdater(projectDir string) *DependencyUpdater

NewDependencyUpdater creates a new DependencyUpdater for the given project directory.

func (*DependencyUpdater) ApplyUpdate 

func (du *DependencyUpdater) ApplyUpdate(dep Dependency) error

ApplyUpdate applies a single dependency update using the appropriate package manager.

func (*DependencyUpdater) BatchUpdate 

func (du *DependencyUpdater) BatchUpdate(deps []Dependency, maxRisk string) ([]string, []error)

BatchUpdate updates dependencies up to the specified risk level. maxRisk can be "patch", "minor", or "major" (includes all lower levels).

func (*DependencyUpdater) DetectLanguage 

func (du *DependencyUpdater) DetectLanguage() string

DetectLanguage determines the project language by checking for known manifest files.

func (*DependencyUpdater) GeneratePlan 

func (du *DependencyUpdater) GeneratePlan(deps []Dependency) *UpdatePlan

GeneratePlan creates an UpdatePlan from a list of dependencies. It prioritizes security fixes, then patch, minor, and major updates.

func (*DependencyUpdater) ListOutdated 

func (du *DependencyUpdater) ListOutdated() ([]Dependency, error)

ListOutdated returns the list of outdated dependencies for the detected language.

type ImpactAnalysis 

type ImpactAnalysis struct {
	ChangedFiles         []string
	DirectlyAffected     []string
	TransitivelyAffected []string
	RiskScore            float64
	TestCoverage         float64
	Suggestions          []string
}

ImpactAnalysis holds the results of analyzing the blast radius of code changes.

type ImpactAnalyzer 

type ImpactAnalyzer struct {
	ProjectDir  string
	ImportGraph map[string][]string // reverse dependency: pkg -> list of packages that import it
	TestMapping map[string][]string // pkg -> list of test files for that pkg
	// contains filtered or unexported fields
}

ImpactAnalyzer predicts the blast radius of code changes before they're applied.

func NewImpactAnalyzer 

func NewImpactAnalyzer(projectDir string) *ImpactAnalyzer

NewImpactAnalyzer creates a new ImpactAnalyzer for the given project directory.

func (*ImpactAnalyzer) Analyze 

func (ia *ImpactAnalyzer) Analyze(changedFiles []string) (*ImpactAnalysis, error)

Analyze performs a full impact analysis for the given changed files.

func (*ImpactAnalyzer) FindDirectDependents 

func (ia *ImpactAnalyzer) FindDirectDependents(pkg string) []string

FindDirectDependents returns packages that directly import the given package.

func (*ImpactAnalyzer) FindTestCoverage 

func (ia *ImpactAnalyzer) FindTestCoverage(packages []string) float64

FindTestCoverage checks which affected packages have test files and returns the percentage of packages with at least one test file.

func (*ImpactAnalyzer) FindTransitiveDependents 

func (ia *ImpactAnalyzer) FindTransitiveDependents(pkg string, depth int) []string

FindTransitiveDependents performs BFS up to depth levels of reverse dependencies.

func (*ImpactAnalyzer) GenerateSuggestions 

func (ia *ImpactAnalyzer) GenerateSuggestions(analysis *ImpactAnalysis) []string

GenerateSuggestions produces actionable suggestions based on the analysis.

func (*ImpactAnalyzer) QuickImpact 

func (ia *ImpactAnalyzer) QuickImpact(file string) string

QuickImpact provides a fast single-file impact summary (one line).

func (*ImpactAnalyzer) ScoreRisk 

func (ia *ImpactAnalyzer) ScoreRisk(analysis *ImpactAnalysis) float64

ScoreRisk calculates a risk score from 0.0 to 1.0 based on various factors.

type MigrationPlan 

type MigrationPlan struct {
	Name             string
	Description      string
	Steps            []MigrationStep
	AffectedFiles    []string
	EstimatedChanges int
	RiskLevel        string
	Validated        bool
	CreatedAt        time.Time
}

MigrationPlan represents a complete plan for a large-scale code migration.

type MigrationPlanner 

type MigrationPlanner struct {
	ProjectDir string
	// contains filtered or unexported fields
}

MigrationPlanner plans and executes large-scale code migrations.

func NewMigrationPlanner 

func NewMigrationPlanner(projectDir string) *MigrationPlanner

NewMigrationPlanner creates a new MigrationPlanner for the given project directory.

func (*MigrationPlanner) Execute 

func (mp *MigrationPlanner) Execute(plan *MigrationPlan) (*MigrationResult, error)

Execute applies all auto steps in the plan, skipping manual ones.

func (*MigrationPlanner) PlanAPIChange 

func (mp *MigrationPlanner) PlanAPIChange(oldSig, newSig string) (*MigrationPlan, error)

PlanAPIChange creates a migration plan for changing a function/method signature.

func (*MigrationPlanner) PlanDependencyUpgrade 

func (mp *MigrationPlanner) PlanDependencyUpgrade(pkg, fromVersion, toVersion string) (*MigrationPlan, error)

PlanDependencyUpgrade creates a migration plan for upgrading a dependency from one version to another.

func (*MigrationPlanner) PlanPatternReplace 

func (mp *MigrationPlanner) PlanPatternReplace(pattern, replacement, fileGlob string) (*MigrationPlan, error)

PlanPatternReplace creates a migration plan to replace all matches of pattern in files matching fileGlob with the given replacement.

func (*MigrationPlanner) PlanRename 

func (mp *MigrationPlanner) PlanRename(oldName, newName string) (*MigrationPlan, error)

PlanRename creates a migration plan to rename oldName to newName across the project. It orders definitions first, then usages.

func (*MigrationPlanner) Preview 

func (mp *MigrationPlanner) Preview(plan *MigrationPlan) string

Preview returns a human-readable preview of the migration plan.

func (*MigrationPlanner) Rollback 

func (mp *MigrationPlanner) Rollback(plan *MigrationPlan) error

Rollback undoes applied steps in reverse order.

func (*MigrationPlanner) Validate 

func (mp *MigrationPlanner) Validate(plan *MigrationPlan) []string

Validate checks the plan for potential issues and returns a list of warnings.

type MigrationResult 

type MigrationResult struct {
	Completed    int
	Skipped      int
	Failed       int
	ManualReview []MigrationStep
}

MigrationResult holds the outcome of executing a migration plan.

type MigrationStep 

type MigrationStep struct {
	Order       int
	Description string
	Pattern     string // regex to find
	Replacement string
	Files       []string
	Manual      bool // needs human review
	Completed   bool
	Error       string
}

MigrationStep represents a single step within a migration plan.

type ModuleInfo 

type ModuleInfo struct {
	Name         string
	Path         string
	Purpose      string
	PublicAPI    []string
	Dependencies []string
	Size         int
}

ModuleInfo describes a single module/package within the project.

type Pattern 

type Pattern struct {
	Name        string
	Description string
	Files       []string
	Confidence  float64
}

Pattern represents an architectural or design pattern detected in the codebase.

func DetectPatterns 

func DetectPatterns(dir string) []Pattern

DetectPatterns identifies design patterns used in the codebase.

type ProjectAnalysis 

type ProjectAnalysis struct {
	Name         string
	Language     string
	Framework    string
	Architecture string
	EntryPoints  []string
	KeyModules   []ModuleInfo
	Patterns     []Pattern
	Conventions  []string
	Dependencies int
	TestCoverage string
	LOC          int
	Complexity   string
}

ProjectAnalysis holds the full analysis of a project's architecture, patterns, and conventions.

type ProjectAnalyzer 

type ProjectAnalyzer struct {
	Dir string
	// contains filtered or unexported fields
}

ProjectAnalyzer performs deep analysis of a codebase to understand its architecture, patterns, and conventions. Inspired by gpt-pilot's importer agent.

func NewProjectAnalyzer 

func NewProjectAnalyzer(dir string) *ProjectAnalyzer

NewProjectAnalyzer creates a new ProjectAnalyzer for the given directory.

func (*ProjectAnalyzer) Analyze 

func (pa *ProjectAnalyzer) Analyze() (*ProjectAnalysis, error)

Analyze performs a full project scan: detects language/framework, maps architecture, identifies entry points, detects patterns, and extracts conventions.

func (*ProjectAnalyzer) AnalyzeModule 

func (pa *ProjectAnalyzer) AnalyzeModule(path string) *ModuleInfo

AnalyzeModule scans a package directory and extracts its public API, line count, and purpose.

type ProjectContext 

type ProjectContext struct {
	ProjectDir string
	Loaded     map[string]string // filename → content
}

ProjectContext loads and manages persistent project knowledge files.

func NewProjectContext 

func NewProjectContext(projectDir string) *ProjectContext

NewProjectContext creates a context loader for the given project directory.

func (*ProjectContext) HasContext 

func (pc *ProjectContext) HasContext() bool

HasContext reports whether any project context files exist.

func (*ProjectContext) InitPrompt 

func (pc *ProjectContext) InitPrompt() string

InitPrompt returns a prompt for hawk to generate initial project-context.md.

func (*ProjectContext) Load 

func (pc *ProjectContext) Load() string

Load reads all project context files and returns combined content.

type ProjectSnapshot 

type ProjectSnapshot struct {
	DirectoryListing string    // ls -1 output of the project root
	RecentCommits    string    // git log --oneline -10
	GitStatus        string    // git status --short
	GatheredAt       time.Time // when this snapshot was created
}

ProjectSnapshot holds a point-in-time view of project state gathered via shell commands.

func (*ProjectSnapshot) ForExploreMode 

func (s *ProjectSnapshot) ForExploreMode() *ProjectSnapshot

ForExploreMode returns a copy of the snapshot with GitStatus cleared. This is useful for read-only agents that don't need working tree state, saving tokens in the prompt.

type ProjectSnapshotCache 

type ProjectSnapshotCache struct {
	// contains filtered or unexported fields
}

ProjectSnapshotCache caches a ProjectSnapshot for a given directory, refreshing it only after the TTL expires. This avoids redundant shell commands when multiple sub-agents spawn in rapid succession against an unchanged repo.

func NewProjectSnapshotCache 

func NewProjectSnapshotCache(dir string, ttl time.Duration) *ProjectSnapshotCache

NewProjectSnapshotCache creates a new ProjectSnapshotCache for the given directory. If ttl is zero, DefaultProjectSnapshotTTL is used.

func (*ProjectSnapshotCache) Get 

func (c *ProjectSnapshotCache) Get(ctx context.Context) *ProjectSnapshot

Get returns a cached project snapshot if it's still valid, or gathers a fresh one by running shell commands. The provided context controls overall cancellation but individual commands have a 2s timeout.

func (*ProjectSnapshotCache) Invalidate 

func (c *ProjectSnapshotCache) Invalidate()

Invalidate forces the next Get call to gather a fresh snapshot.

type Release 

type Release struct {
	Version         string
	Date            time.Time
	Changes         []ChangeEntry
	BreakingChanges []ChangeEntry
	Contributors    []string
	Stats           ReleaseStats
}

Release represents a prepared release with all associated metadata.

type ReleaseManager 

type ReleaseManager struct {
	ProjectDir     string
	CurrentVersion string
	// contains filtered or unexported fields
}

ReleaseManager handles release automation including changelog generation, version bumping, and release preparation.

func NewReleaseManager 

func NewReleaseManager(projectDir string) *ReleaseManager

NewReleaseManager creates a new ReleaseManager for the given project directory.

func (*ReleaseManager) DetectCurrentVersion 

func (rm *ReleaseManager) DetectCurrentVersion() (string, error)

DetectCurrentVersion reads the current version from git tags, go.mod, package.json, or Cargo.toml.

func (*ReleaseManager) GatherChanges 

func (rm *ReleaseManager) GatherChanges(sinceTag string) ([]ChangeEntry, error)

GatherChanges collects and parses all commits since the given tag.

func (*ReleaseManager) PrepareRelease 

func (rm *ReleaseManager) PrepareRelease() (*Release, error)

PrepareRelease gathers changes since the last tag, bumps the version, generates changelog, and returns the release ready for review.

func (*ReleaseManager) ValidateRelease 

func (rm *ReleaseManager) ValidateRelease(release *Release) []string

ValidateRelease checks that a release is valid and ready to be published. Returns a list of validation issues (empty if valid).

type ReleaseStats 

type ReleaseStats struct {
	Commits      int
	FilesChanged int
	Additions    int
	Deletions    int
	Contributors int
}

ReleaseStats holds numerical statistics for a release.

type UpdatePlan 

type UpdatePlan struct {
	Dependencies      []Dependency
	RiskLevel         string // "low", "medium", "high"
	TestCommand       string
	RollbackCommand   string
	EstimatedBreaking int
}

UpdatePlan represents a structured plan for updating dependencies.

type Violation 

type Violation struct {
	Convention string
	File       string
	Line       int
	Code       string
	Expected   string
	Got        string
}

Violation records a single convention violation in generated code.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.