@kujolang/paperclip 0.1.0

package/bundled/components/patchbrief/src/git.kujo

@@ -0,0 +1,250 @@
+# Git command wrappers for PatchBrief.
+# Provides safe wrappers around git commands for diff inspection.
+# Uses Kujo's execute built-in for process execution.
+
+from src.common import str_starts_with, str_contains, str_trim, shell_quote
+
+DIFF_ANALYSIS_MAX_BYTES := 1048576
+
+func push_unique(items, value) {
+	text := to_string(value)
+	idx := 0
+	while idx < len(items) {
+		if to_string(items[idx]) == text {
+			return items
+		}
+		idx := idx + 1
+	}
+	return push(items, text)
+}
+
+# Check if the current directory is inside a git repository.
+export func is_git_repo() {
+	try {
+		_ := execute("git rev-parse --git-dir 2>/dev/null", {"timeout_ms": 5000})
+		return true
+	} except err {
+		return false
+	}
+}
+
+# Get the current branch name.
+export func current_branch() {
+	try {
+		result := execute("git symbolic-ref --short HEAD", {"timeout_ms": 5000})
+		branch := trim(to_string(result))
+		if branch != "" {
+			return branch
+		}
+	} except err {
+		try {
+			short := execute("git rev-parse --short HEAD", {"timeout_ms": 5000})
+			return "HEAD@" + trim(to_string(short))
+		} except err2 {
+			return "unknown"
+		}
+	}
+	return "unknown"
+}
+
+# Get the repository name from the remote origin URL or directory name.
+export func repo_name() {
+	try {
+		url := execute("git remote get-url origin 2>/dev/null", {"timeout_ms": 5000})
+		url_str := str_trim(to_string(url))
+		if url_str != "" && str_starts_with(url_str, "fatal") == false {
+			parts := split(url_str, "/")
+			last := str_trim(parts[len(parts) - 1])
+			if str_contains(last, ":") {
+				colon_parts := split(last, ":")
+				last = str_trim(colon_parts[len(colon_parts) - 1])
+			}
+			if ends_with(last, ".git") {
+				last = substring(last, 0, len(last) - 4)
+			}
+			if last != "" {
+				return last
+			}
+		}
+	} except err {}
+	try {
+		root := execute("git rev-parse --show-toplevel", {"timeout_ms": 5000})
+		return basename(str_trim(to_string(root)))
+	} except err2 {
+		return "unknown"
+	}
+}
+
+# Get the diff stat summary (files changed, insertions, deletions).
+export func diff_stat() {
+	try {
+		output := execute("git diff --no-ext-diff --stat HEAD 2>/dev/null", {"timeout_ms": 10000})
+		text := to_string(output)
+		if str_trim(text) == "" {
+			return {"ok": true, "output": "", "files": 0, "added": 0, "removed": 0}
+		}
+		lines := split(text, "\n")
+		summary_line := ""
+		idx := len(lines) - 1
+		while idx >= 0 {
+			line := str_trim(to_string(lines[idx]))
+			if line != "" {
+				summary_line := line
+				idx := -1
+			}
+			idx := idx - 1
+		}
+		files_count := 0
+		added_count := 0
+		removed_count := 0
+		if summary_line != "" && str_contains(summary_line, "changed") {
+			comma_parts := split(summary_line, ",")
+			ci := 0
+			while ci < len(comma_parts) {
+				part := str_trim(to_string(comma_parts[ci]))
+				if str_contains(part, "file") {
+					num_str := replace(replace(part, " files changed", ""), " file changed", "")
+					num_str := str_trim(num_str)
+					files_count := to_int(num_str)
+				}
+				if str_contains(part, "insertion") {
+					num_str := replace(replace(part, " insertions(+)", ""), " insertion(+)", "")
+					num_str := str_trim(num_str)
+					added_count := to_int(num_str)
+				}
+				if str_contains(part, "deletion") {
+					num_str := replace(replace(part, " deletions(-)", ""), " deletion(-)", "")
+					num_str := str_trim(num_str)
+					removed_count := to_int(num_str)
+				}
+				ci := ci + 1
+			}
+		}
+		return {
+			"ok": true,
+			"output": text,
+			"files": files_count,
+			"added": added_count,
+			"removed": removed_count
+		}
+	} except err {
+		return {"ok": false, "output": "", "files": 0, "added": 0, "removed": 0}
+	}
+}
+
+# Get the list of changed files.
+export func changed_files() {
+	return changed_files_result()["files"]
+}
+
+export func changed_files_result() {
+	try {
+		output := execute("git status --porcelain=v1 -z --untracked-files=all 2>/dev/null", {"timeout_ms": 10000})
+		text := to_string(output)
+		if text == "" {
+			return {"ok": true, "files": []}
+		}
+		files := []
+		nul := parse_json("\"\\u0000\"")
+		entries := split(text, nul)
+		idx := 0
+		while idx < len(entries) {
+			entry := to_string(entries[idx])
+			if len(entry) >= 3 {
+				status := substring(entry, 0, 2)
+				path_text := substring(entry, 3, len(entry))
+				if path_text != "" {
+					files := push_unique(files, path_text)
+				}
+				if str_contains(status, "R") || str_contains(status, "C") {
+					idx := idx + 1
+				}
+			}
+			idx := idx + 1
+		}
+		return {"ok": true, "files": files}
+	} except err {
+		return {"ok": false, "files": []}
+	}
+}
+
+# Get the full diff output.
+export func full_diff() {
+	return full_diff_analysis()["text"]
+}
+
+# Read a bounded diff and report whether heuristic analysis may be incomplete.
+export func full_diff_analysis() {
+	return full_diff_analysis_with_limit(DIFF_ANALYSIS_MAX_BYTES)
+}
+
+export func full_diff_analysis_with_limit(max_bytes) {
+	limit := to_int(max_bytes)
+	if limit < 1024 {
+		limit = 1024
+	}
+	if limit > 16777216 {
+		limit = 16777216
+	}
+	try {
+		result := spawn_process(["git", "diff", "--no-ext-diff", "HEAD"], {"timeout_ms": 30000, "max_output_bytes": limit})
+		if result.success == false && result.timed_out == false {
+			# An unborn repository has no HEAD; compare its index with the empty tree.
+			result = spawn_process(["git", "diff", "--no-ext-diff", "--cached"], {"timeout_ms": 30000, "max_output_bytes": limit})
+		}
+		text := to_string(result.stdout)
+		failed := result.success == false || result.timed_out == true
+		return {
+			"text": text,
+			"bytes_analyzed": len(text),
+			"max_bytes": limit,
+			"truncated": result.stdout_truncated,
+			"error": failed
+		}
+	} except err {
+		return {"text": "", "bytes_analyzed": 0, "max_bytes": limit, "truncated": false, "error": true}
+	}
+}
+
+# Get the diff for a specific file.
+export func file_diff(file_path) {
+	try {
+		cmd := "git diff --no-ext-diff HEAD -- " + shell_quote(file_path)
+		output := execute(cmd, {"timeout_ms": 10000})
+		return to_string(output)
+	} except err {
+		return ""
+	}
+}
+
+# Get the shortlog between current state and last commit.
+export func recent_commits(count) {
+	try {
+		safe_count := to_int(count)
+		if safe_count < 1 {
+			safe_count := 1
+		}
+		if safe_count > 100 {
+			safe_count := 100
+		}
+		cmd := "git log --oneline -" + to_string(safe_count) + " 2>/dev/null"
+		output := execute(cmd, {"timeout_ms": 10000})
+		text := str_trim(to_string(output))
+		if text == "" {
+			return []
+		}
+		commits := []
+		lines := split(text, "\n")
+		idx := 0
+		while idx < len(lines) {
+			line := str_trim(to_string(lines[idx]))
+			if line != "" {
+				commits := push(commits, line)
+			}
+			idx := idx + 1
+		}
+		return commits
+	} except err {
+		return []
+	}
+}

package/bundled/components/patchbrief/src/handoff.kujo

@@ -0,0 +1,145 @@
+# Handoff module — generates structured handoff notes for reviewers or downstream agents.
+
+from src.git import is_git_repo, current_branch, repo_name, diff_stat, changed_files_result, full_diff_analysis, recent_commits
+from src.common import timestamp_now, str_join, markdown_text, markdown_code, print_lines, print_prefixed_lines, print_prefixed_or_fallback, print_markdown_section, print_markdown_paragraph, print_fenced, print_not_git_repo_error
+from src.summarize import infer_purpose, identify_risks
+
+REVIEWER_CHECKLIST := [
+	"Changes look correct",
+	"Tests pass",
+	"No security concerns",
+	"Documentation updated if needed"
+]
+
+NEXT_AGENT_COMMANDS := [
+	"kujo run patchbrief.kujo -- summarize",
+	"kujo run patchbrief.kujo -- suggest-tests"
+]
+
+# Generate a Markdown handoff note.
+export func handoff_markdown() {
+	if is_git_repo() == false {
+		print_not_git_repo_error()
+		exit(1)
+	}
+	branch := current_branch()
+	repo := repo_name()
+	stat := diff_stat()
+	files_result := changed_files_result()
+	if files_result["ok"] == false {
+		print_lines(["Error: Failed to inspect git working tree."])
+		exit(1)
+	}
+	files := files_result["files"]
+	diff_analysis := full_diff_analysis()
+	diff_text := diff_analysis["text"]
+	purpose := infer_purpose(files, diff_text)
+	risks := identify_risks(files, diff_text)
+	if diff_analysis["error"] == true {
+		risks := push(risks, "Diff content analysis failed — purpose and content-based risk hints may be incomplete")
+	} else if diff_analysis["truncated"] == true {
+		risks := push(risks, "Diff analysis was truncated at " + to_string(diff_analysis["max_bytes"]) + " bytes — purpose and content-based risk hints may be incomplete")
+	}
+	commits := recent_commits(5)
+	ts := timestamp_now()
+	print_lines([
+		"# Handoff Note: " + markdown_text(repo) + " — " + markdown_text(branch),
+		"",
+		"**Date:** " + ts,
+		"**Branch:** " + markdown_text(branch),
+		"**Changed Files:** " + to_string(len(files)) + " (+" + to_string(stat["added"]) + "/-" + to_string(stat["removed"]) + ")"
+	])
+	print_markdown_section("Summary")
+	print_markdown_paragraph(purpose)
+	print_markdown_section("What Changed")
+	file_lines := []
+	fi := 0
+	while fi < len(files) {
+		file_lines := push(file_lines, "- " + markdown_code(files[fi]))
+		fi := fi + 1
+	}
+	print_lines(file_lines)
+	print_markdown_section("Risk Assessment")
+	print_prefixed_lines(risks, "- ")
+	print_markdown_section("Recent Commits")
+	safe_commits := []
+	ci := 0
+	while ci < len(commits) {
+		safe_commits := push(safe_commits, markdown_text(commits[ci]))
+		ci := ci + 1
+	}
+	print_prefixed_or_fallback(safe_commits, "- ", "No recent commits found.")
+	print_markdown_section("Reviewer Notes")
+	print_prefixed_lines(REVIEWER_CHECKLIST, "- [ ] ")
+	print_markdown_section("For the Next Agent/Developer")
+	print_fenced(str_join(NEXT_AGENT_COMMANDS, "\n"))
+	print_lines([
+		"",
+		"---",
+		"*Handoff generated by PatchBrief v1.0.1 at " + ts + "*"
+	])
+}
+
+# Generate a JSON handoff note.
+export func handoff_json(pretty_json) {
+	if is_git_repo() == false {
+		error_obj := {
+			"error": true,
+			"message": "Not a git repository. Run patchbrief inside a git repo."
+		}
+		if pretty_json == true { print(to_json_pretty(error_obj)) } else { print(to_json(error_obj)) }
+		exit(1)
+	}
+	branch := current_branch()
+	repo := repo_name()
+	stat := diff_stat()
+	files_result := changed_files_result()
+	if files_result["ok"] == false {
+		error_obj := {"error": true, "message": "Failed to inspect git working tree."}
+		if pretty_json == true { print(to_json_pretty(error_obj)) } else { print(to_json(error_obj)) }
+		exit(1)
+	}
+	files := files_result["files"]
+	diff_analysis := full_diff_analysis()
+	diff_text := diff_analysis["text"]
+	purpose := infer_purpose(files, diff_text)
+	risks := identify_risks(files, diff_text)
+	if diff_analysis["error"] == true {
+		risks := push(risks, "Diff content analysis failed — purpose and content-based risk hints may be incomplete")
+	} else if diff_analysis["truncated"] == true {
+		risks := push(risks, "Diff analysis was truncated at " + to_string(diff_analysis["max_bytes"]) + " bytes — purpose and content-based risk hints may be incomplete")
+	}
+	commits := recent_commits(5)
+	ts := timestamp_now()
+	# Build file array
+	file_list := []
+	fi := 0
+	while fi < len(files) {
+		file_list := push(file_list, to_string(files[fi]))
+		fi := fi + 1
+	}
+	output := {
+		"format": "patchbrief-handoff",
+		"version": "1.0.1",
+		"generated_at": ts,
+		"repo": repo,
+		"branch": branch,
+		"summary": {
+			"files_changed": len(files),
+			"lines_added": stat["added"],
+			"lines_removed": stat["removed"],
+			"likely_purpose": purpose
+		},
+		"analysis": {
+			"diff_bytes_analyzed": diff_analysis["bytes_analyzed"],
+			"diff_error": diff_analysis["error"],
+			"diff_max_bytes": diff_analysis["max_bytes"],
+			"diff_truncated": diff_analysis["truncated"]
+		},
+		"files": file_list,
+		"risk_areas": risks,
+		"recent_commits": commits,
+		"reviewer_checklist": REVIEWER_CHECKLIST
+	}
+	if pretty_json == true { print(to_json_pretty(output)) } else { print(to_json(output)) }
+}

package/bundled/components/patchbrief/src/suggest_tests.kujo

@@ -0,0 +1,137 @@
+# Suggest tests module — analyzes changed files and suggests test commands.
+
+from src.git import is_git_repo, changed_files_result
+from src.common import str_contains, str_lower, str_ends_with, dict_has_key, markdown_code, print_lines, print_prefixed_lines, print_wrapped_lines, print_markdown_section, print_not_git_repo_error
+
+# File pattern to test suggestion mapping.
+TEST_SUGGESTIONS := {
+	".kujo": ["kujo test"],
+	".rs": ["cargo test", "cargo clippy --all-targets --all-features -- -D warnings"],
+	".py": ["python -m pytest", "python -m unittest discover"],
+	".js": ["npm test", "npx jest"],
+	".ts": ["npm test", "npx jest", "npx tsc --noEmit"],
+	".jsx": ["npm test", "npx jest"],
+	".tsx": ["npm test", "npx jest", "npx tsc --noEmit"],
+	".php": ["php vendor/bin/phpunit", "php artisan test"],
+	".rb": ["bundle exec rspec", "bundle exec rake test"],
+	".go": ["go test ./...", "go vet ./..."],
+	".java": ["./gradlew test", "mvn test"],
+	".kt": ["./gradlew test"],
+	".swift": ["swift test", "xcodebuild test"],
+	".sh": ["shellcheck *.sh", "bash -n script.sh"],
+	".md": ["markdownlint *.md"],
+	".css": ["npx stylelint '**/*.css'"],
+	".json": ["npx jsonlint --quiet *.json"],
+	".yaml": ["yamllint ."],
+	".yml": ["yamllint ."],
+	".sql": ["# Review migration safety manually"],
+	".dockerfile": ["docker build --check .", "hadolint Dockerfile"],
+	".tf": ["terraform validate", "terraform fmt -check"]
+}
+
+GENERAL_VALIDATION := [
+	"Review all changed files for correctness",
+	"Check for leftover debug logging or commented-out code",
+	"Verify any new configuration values are documented"
+]
+
+# Get unique test suggestions for a set of files.
+export func suggestions_for_files(files_list) {
+	suggestions_set := {}
+	result := []
+	fi := 0
+	while fi < len(files_list) {
+		f := str_lower(to_string(files_list[fi]))
+		is_dockerfile := f == "dockerfile" || str_ends_with(f, "/dockerfile") || str_ends_with(f, ".dockerfile")
+		extensions := [".kujo", ".rs", ".py", ".js", ".ts", ".jsx", ".tsx", ".php", ".rb", ".go", ".java", ".kt", ".swift", ".sh", ".md", ".css", ".json", ".yaml", ".yml", ".sql", ".dockerfile", ".tf"]
+		ei := 0
+		while ei < len(extensions) {
+			ext := to_string(extensions[ei])
+			is_match := false
+			if ext == ".dockerfile" {
+				is_match := is_dockerfile
+			} else {
+				is_match := str_ends_with(f, ext)
+			}
+			if is_match {
+				cmds := TEST_SUGGESTIONS[ext]
+				ci := 0
+				while ci < len(cmds) {
+					cmd := to_string(cmds[ci])
+					# Check if already added
+					if dict_has_key(suggestions_set, cmd) == false {
+						suggestions_set[cmd] := true
+						result := push(result, cmd)
+					}
+					ci := ci + 1
+				}
+			}
+			ei := ei + 1
+		}
+		fi := fi + 1
+	}
+	if len(result) == 0 {
+		result := push(result, "# No specific test commands found — review changes manually")
+	}
+	return result
+}
+
+export func manual_checks_for_file(file_path) {
+	file_name := to_string(file_path)
+	lower_file := str_lower(file_name)
+	checks := []
+	if str_contains(lower_file, "readme") || str_ends_with(lower_file, ".md") {
+		checks := push(checks, "Preview Markdown rendering for " + markdown_code(file_name))
+	}
+	if str_contains(lower_file, "config") || str_contains(lower_file, ".env") {
+		checks := push(checks, "Verify environment-specific values in " + markdown_code(file_name))
+	}
+	if str_contains(lower_file, "migration") || str_contains(lower_file, "schema") {
+		checks := push(checks, "Test migration rollback for " + markdown_code(file_name))
+	}
+	return checks
+}
+
+# Generate test suggestions.
+export func suggest_tests() {
+	if is_git_repo() == false {
+		print_not_git_repo_error()
+		exit(1)
+	}
+	files_result := changed_files_result()
+	if files_result["ok"] == false {
+		print_lines(["Error: Failed to inspect git working tree."])
+		exit(1)
+	}
+	files := files_result["files"]
+	if len(files) == 0 {
+		print_lines([
+			"# PatchBrief Test Suggestions",
+			"",
+			"No uncommitted changes detected. Nothing to test."
+		])
+		return
+	}
+	print_lines([
+		"# PatchBrief Test Suggestions",
+		"",
+		"Based on the changed files, consider running:",
+		""
+	])
+	suggestions := suggestions_for_files(files)
+	print_wrapped_lines(suggestions, "- `", "`")
+	print_markdown_section("General Validation")
+	print_wrapped_lines(GENERAL_VALIDATION, "- ", "")
+	print_markdown_section("Manual Checks")
+	# Per-file suggestions
+	fi_idx := 0
+	while fi_idx < len(files) {
+		print_prefixed_lines(manual_checks_for_file(files[fi_idx]), "- ")
+		fi_idx := fi_idx + 1
+	}
+	print_lines([
+		"",
+		"---",
+		"*Generated by PatchBrief v1.0.1*"
+	])
+}