@kujolang/paperclip 0.1.0

package/bundled/components/changebucket/src/diffsrc.kujo

@@ -0,0 +1,252 @@
+# ChangeBucket :: diffsrc
+#
+# The git interface. Everything here is READ-ONLY: it only ever runs
+# rev-parse / diff / ls-files. Nothing stages, commits, resets, cleans,
+# checks out, stashes, or applies. It tolerates the absence of git or of a
+# repository so callers always get a structured answer.
+#
+# Two analysis shapes are supported:
+#   worktree mode  — compare the working tree (incl. untracked files) to a base
+#                    ref (default HEAD, or the empty tree for a repo with no
+#                    commits yet).
+#   range mode     — compare two commits, base..head (no working-tree/untracked).
+
+from src.util import basename
+
+# The well-known empty-tree object. Diffing against it yields "everything is an
+# addition", which is exactly what we want for a repo that has no commits yet.
+func empty_tree() {
+    return "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+}
+
+# Quote a path for safe inclusion in a shell command (POSIX single-quote rules).
+func shq(path) {
+    escaped := replace_str(path, "'", "'\\''")
+    return "'" + escaped + "'"
+}
+
+# Run a read-only git command against `repo_path`. `-C` keeps us in the target
+# repo without changing cwd; quotePath=false stops git from octal-escaping
+# non-ASCII paths so our tab parsing stays simple.
+func git(repo_path, subcmd) {
+    cmd := "git -C " + shq(repo_path) + " -c core.quotePath=false " + subcmd
+    return execute_status(cmd)
+}
+
+# Reject ref inputs that are unsafe or ambiguous to pass through the shell/git.
+# This keeps user-supplied --base/--head values from being interpreted as shell
+# syntax or git options.
+func has_unsafe_ref_char(ref) {
+    bad := [" ", "\t", "\n", "\r", "'", "\"", ";", "&", "|", "`", "$", "(", ")", "<", ">", "\\"]
+    for ch in bad {
+        if contains(ref, ch) == 1 {
+            return true
+        }
+    }
+    return false
+}
+
+func safe_ref_value(ref) {
+    if type(ref) == "null" || ref == "" {
+        return false
+    }
+    if starts_with(ref, "-") {
+        return false
+    }
+    if has_unsafe_ref_char(ref) {
+        return false
+    }
+    return true
+}
+
+# True if git exists and `repo_path` is inside a working tree.
+export func is_repo(repo_path) {
+    r := git(repo_path, "rev-parse --is-inside-work-tree")
+    if r.exitcode == 0 && trim(r.stdout) == "true" {
+        return true
+    }
+    return false
+}
+
+# Current commit hash, or null when there is none (no git, no repo, no commits).
+export func head_commit(repo_path) {
+    r := git(repo_path, "rev-parse HEAD")
+    if r.exitcode == 0 {
+        return trim(r.stdout)
+    }
+    return null
+}
+
+# Canonical repository root. Git diff paths are root-relative even when `-C`
+# points at a subdirectory, so all file access and untracked paths must use the
+# same root or the model mixes incompatible path bases.
+export func repo_root(repo_path) {
+    r := git(repo_path, "rev-parse --show-toplevel")
+    if r.exitcode == 0 {
+        mut root := r.stdout
+        if ends_with(root, "\n") {
+            root = substring(root, 0, len(root) - 1)
+        }
+        if ends_with(root, "\r") {
+            root = substring(root, 0, len(root) - 1)
+        }
+        return root
+    }
+    return repo_path
+}
+
+# Decide what we are diffing and produce a stable description:
+#   {mode, spec, base_label, head_label, include_untracked}
+# `spec` is the argument handed to `git diff` (a single ref in worktree mode,
+# or "base..head" in range mode).
+export func resolve_refs(repo_path, base_flag, head_flag) {
+    if type(head_flag) != "null" && head_flag != "" {
+        mut base := "HEAD"
+        if type(base_flag) != "null" && base_flag != "" {
+            base = base_flag
+        }
+        if safe_ref_value(base) == false {
+            return {"error": "invalid --base ref: " + base}
+        }
+        if safe_ref_value(head_flag) == false {
+            return {"error": "invalid --head ref: " + head_flag}
+        }
+        return {
+            "mode": "range",
+            "spec": base + ".." + head_flag,
+            "base_label": base,
+            "head_label": head_flag,
+            "include_untracked": false
+        }
+    }
+    # worktree mode
+    mut base := ""
+    mut base_label := ""
+    if type(base_flag) != "null" && base_flag != "" {
+        if safe_ref_value(base_flag) == false {
+            return {"error": "invalid --base ref: " + base_flag}
+        }
+        base = base_flag
+        base_label = base_flag
+    } else {
+        hc := head_commit(repo_path)
+        if type(hc) == "null" {
+            base = empty_tree()
+            base_label = "(empty tree)"
+        } else {
+            base = "HEAD"
+            base_label = "HEAD"
+        }
+    }
+    return {
+        "mode": "worktree",
+        "spec": base,
+        "base_label": base_label,
+        "head_label": "working tree",
+        "include_untracked": true
+    }
+}
+
+func diff_spec_arg(refs) {
+    return shq(refs["spec"])
+}
+
+# Validate the resolved diff spec once up front so a bad ref does not look like
+# a legitimate empty change.
+export func validate_diff(repo_path, refs) {
+    r := git(repo_path, "diff --name-status --no-renames " + diff_spec_arg(refs))
+    if r.exitcode == 0 {
+        return ""
+    }
+    mut msg := trim(r.stderr)
+    if msg == "" {
+        msg = trim(r.stdout)
+    }
+    if msg == "" {
+        msg = "git diff failed"
+    }
+    return "invalid git revision or range '" + refs["spec"] + "': " + msg
+}
+
+# NUL-delimited `git diff --numstat` output for the resolved spec
+# (added\tdeleted\tpath\0; "-" for binary). Renames are disabled.
+export func numstat_text(repo_path, refs) {
+    r := git(repo_path, "diff --numstat -z --no-renames " + diff_spec_arg(refs))
+    if r.exitcode == 0 {
+        return r.stdout
+    }
+    return ""
+}
+
+# NUL-delimited `git diff --name-status` output (status\0path\0).
+export func namestatus_text(repo_path, refs) {
+    r := git(repo_path, "diff --name-status -z --no-renames " + diff_spec_arg(refs))
+    if r.exitcode == 0 {
+        return r.stdout
+    }
+    return ""
+}
+
+# Untracked files not yet known to git (respecting .gitignore).
+export func untracked_list(repo_path) {
+    mut out := []
+    r := git(repo_path, "ls-files --full-name --others --exclude-standard -z")
+    if r.exitcode != 0 {
+        return out
+    }
+    nul := parse_json("\"\\u0000\"")
+    paths := split(r.stdout, nul)
+    for name in paths {
+        if name != "" {
+            out = push(out, name)
+        }
+    }
+    return out
+}
+
+# Treat a path as binary purely by extension. Used for untracked files, where
+# numstat cannot tell us. Keeps us from trying to line-count an image or
+# archive.
+export func is_binary_path(path) {
+    pl := to_lower(path)
+    exts := [".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".webp", ".pdf", ".zip", ".gz", ".tar", ".tgz", ".bz2", ".7z", ".rar", ".woff", ".woff2", ".ttf", ".eot", ".otf", ".mp4", ".mp3", ".wav", ".mov", ".avi", ".class", ".jar", ".so", ".dylib", ".dll", ".exe", ".bin", ".wasm", ".o", ".a", ".lockb", ".db", ".sqlite", ".pyc", ".woff", ".pkl"]
+    for e in exts {
+        if ends_with(pl, e) {
+            return true
+        }
+    }
+    return false
+}
+
+# Count the lines in an untracked text file (its "additions"). Tolerates a
+# missing/unreadable file by returning 0.
+export func count_added_lines(repo_path, path) {
+    full := join_path(repo_path, path)
+    if file_exists(full) == false {
+        return 0
+    }
+    # Git records a symbolic link as one line containing its target. Reading
+    # the path would instead follow it, producing wrong churn and potentially
+    # inspecting data outside the repository.
+    if path_is_symlink(full) {
+        return 1
+    }
+    if path_is_file(full) == false {
+        return 0
+    }
+    mut content := ""
+    try {
+        content = read_file(full)
+    } except read_error {
+        return 0
+    }
+    if content == "" {
+        return 0
+    }
+    parts := split(content, "\n")
+    n := len(parts)
+    if parts[n - 1] == "" {
+        return n - 1
+    }
+    return n
+}

package/bundled/components/changebucket/src/render.kujo

@@ -0,0 +1,346 @@
+# ChangeBucket :: render
+#
+# Pure presentation: turn an analysis model into a compact text report or a
+# markdown report. Nothing here touches disk or git. (JSON output is just
+# `to_json_pretty(model)` and lives in the CLI.)
+#
+# Loops are index/`while` based so the module compiles under the checker.
+
+from src.util import commas, display_path
+from src.classify import category_order
+
+# Friendly label for a category key.
+func category_labels() {
+    return {
+        "source": "Source",
+        "tests": "Tests",
+        "docs": "Docs",
+        "config": "Config",
+        "dependency_manifests": "Dependency manifests",
+        "lockfiles": "Lockfiles",
+        "generated": "Generated",
+        "ci": "CI",
+        "scripts": "Scripts",
+        "other": "Other"
+    }
+}
+
+func cat_label(key) {
+    labels := category_labels()
+    if has_key(labels, key) == 1 {
+        return labels[key]
+    }
+    return "Other"
+}
+
+func mark(ok) {
+    if ok {
+        return "PASS"
+    }
+    return "FAIL"
+}
+
+func append_lines(out, lines) {
+    mut next := out
+    mut i := 0
+    while i < len(lines) {
+        next = push(next, lines[i])
+        i = i + 1
+    }
+    return next
+}
+
+func append_text_rows(out, rows) {
+    mut next := out
+    mut i := 0
+    while i < len(rows) {
+        row := rows[i]
+        next = push(next, "- " + row[0] + ": " + row[1])
+        i = i + 1
+    }
+    return next
+}
+
+# Files sorted by churn descending, truncated to `n`. A copy is sorted in place
+# via selection sort (no sort builtin is relied on).
+export func top_by_churn(files, n) {
+    mut arr := []
+    mut i := 0
+    while i < len(files) {
+        arr = push(arr, files[i])
+        i = i + 1
+    }
+    mut a := 0
+    while a < len(arr) {
+        mut best := a
+        mut b := a + 1
+        while b < len(arr) {
+            if arr[b]["churn"] > arr[best]["churn"] {
+                best = b
+            }
+            b = b + 1
+        }
+        if best != a {
+            tmp := arr[a]
+            arr[a] := arr[best]
+            arr[best] := tmp
+        }
+        a = a + 1
+    }
+    mut out := []
+    mut k := 0
+    while k < len(arr) && k < n {
+        out = push(out, arr[k])
+        k = k + 1
+    }
+    return out
+}
+
+func metric_value(summary, key) {
+    if key == "risk_level" {
+        return summary[key]
+    }
+    return commas(summary[key])
+}
+
+func summary_rows(summary, specs) {
+    mut rows := []
+    mut i := 0
+    while i < len(specs) {
+        spec := specs[i]
+        rows = push(rows, [spec[0], metric_value(summary, spec[1])])
+        i = i + 1
+    }
+    return rows
+}
+
+func text_summary_specs() {
+    return [
+        ["Files changed", "files_changed"],
+        ["Lines added", "lines_added"],
+        ["Lines deleted", "lines_deleted"],
+        ["Total line churn", "total_churn"],
+        ["Files added", "files_added"],
+        ["Files modified", "files_modified"],
+        ["Files deleted", "files_deleted"],
+        ["Binary files", "binary_files"],
+        ["Risk level", "risk_level"]
+    ]
+}
+
+func markdown_summary_specs() {
+    return [
+        ["Files changed", "files_changed"],
+        ["Files added", "files_added"],
+        ["Files modified", "files_modified"],
+        ["Files deleted", "files_deleted"],
+        ["Binary files", "binary_files"],
+        ["Lines added", "lines_added"],
+        ["Lines deleted", "lines_deleted"],
+        ["Total churn", "total_churn"],
+        ["Risk level", "risk_level"]
+    ]
+}
+
+func budget_limit_line(label, limit, actual, ok) {
+    return "- " + label + ": " + commas(limit) + " [" + mark(ok) + "] (actual " + commas(actual) + ")"
+}
+
+func budget_ban_line(label, ok) {
+    return "- " + label + " allowed: no [" + mark(ok) + "]"
+}
+
+# Budget lines for the text report, derived from the config so each configured
+# constraint shows its limit and a PASS/FAIL marker.
+func budget_text_lines(model, cfg) {
+    s := model["summary"]
+    cats := model["categories"]
+    mut lines := []
+    if type(cfg["max_files"]) != "null" {
+        lines = push(lines, budget_limit_line("Max files", cfg["max_files"], s["files_changed"], s["files_changed"] <= cfg["max_files"]))
+    }
+    if type(cfg["max_churn"]) != "null" {
+        lines = push(lines, budget_limit_line("Max churn", cfg["max_churn"], s["total_churn"], s["total_churn"] <= cfg["max_churn"]))
+    }
+    if type(cfg["max_additions"]) != "null" {
+        lines = push(lines, budget_limit_line("Max additions", cfg["max_additions"], s["lines_added"], s["lines_added"] <= cfg["max_additions"]))
+    }
+    if type(cfg["max_deletions"]) != "null" {
+        lines = push(lines, budget_limit_line("Max deletions", cfg["max_deletions"], s["lines_deleted"], s["lines_deleted"] <= cfg["max_deletions"]))
+    }
+    if cfg["no_deletes"] == true {
+        lines = push(lines, budget_ban_line("Deletes", s["files_deleted"] == 0))
+    }
+    if cfg["no_dependency_changes"] == true {
+        lines = push(lines, budget_ban_line("Dependency changes", len(cats["dependency_manifests"]) == 0))
+    }
+    if cfg["no_lockfile_changes"] == true {
+        lines = push(lines, budget_ban_line("Lockfile changes", len(cats["lockfiles"]) == 0))
+    }
+    if cfg["no_config_changes"] == true {
+        lines = push(lines, budget_ban_line("Config changes", len(cats["config"]) == 0))
+    }
+    if cfg["no_generated_changes"] == true {
+        lines = push(lines, budget_ban_line("Generated changes", len(cats["generated"]) == 0))
+    }
+    return lines
+}
+
+# Compact, human-readable terminal report.
+export func render_text(model, cfg, show_budget) {
+    s := model["summary"]
+    cats := model["categories"]
+    mut out := []
+    out = append_lines(out, [
+        "ChangeBucket",
+        "",
+        "Base: " + model["base"],
+        "Head: " + model["head"],
+        "",
+        "Summary:"
+    ])
+    summary := summary_rows(s, text_summary_specs())
+    out = append_text_rows(out, summary)
+    out = append_lines(out, ["", "Categories:"])
+    order := category_order()
+    mut ci := 0
+    while ci < len(order) {
+        key := order[ci]
+        count := len(cats[key])
+        if count > 0 {
+            out = push(out, "- " + pad_right(cat_label(key) + ":", 22, " ") + commas(count))
+        }
+        ci = ci + 1
+    }
+
+    largest := top_by_churn(model["files"], 5)
+    if len(largest) > 0 {
+        out = append_lines(out, ["", "Largest changes:"])
+        mut li := 0
+        while li < len(largest) {
+            f := largest[li]
+            out = push(out, "- " + display_path(f["path"]) + " (" + f["status"] + ", +" + commas(f["additions"]) + " -" + commas(f["deletions"]) + ", churn " + commas(f["churn"]) + ")")
+            li = li + 1
+        }
+    }
+
+    if show_budget && model["budget"]["checked"] == true {
+        out = append_lines(out, ["", "Budget:"])
+        blines := budget_text_lines(model, cfg)
+        if len(blines) == 0 {
+            out = push(out, "- (no constraints set)")
+        } else {
+            out = append_lines(out, blines)
+        }
+        if model["budget"]["passed"] == true {
+            out = append_lines(out, ["", "Result: within budget"])
+        } else {
+            out = append_lines(out, ["", "Result: budget exceeded"])
+            failures := model["budget"]["failures"]
+            mut fi := 0
+            while fi < len(failures) {
+                out = push(out, "  - " + failures[fi])
+                fi = fi + 1
+            }
+        }
+    }
+
+    return join(out, "\n")
+}
+
+func md_row(cells) {
+    return "| " + join(cells, " | ") + " |"
+}
+
+func append_md_rows(out, rows) {
+    mut next := out
+    mut i := 0
+    while i < len(rows) {
+        next = push(next, md_row(rows[i]))
+        i = i + 1
+    }
+    return next
+}
+
+func append_md_table(out, header, separator, rows) {
+    mut next := out
+    next = push(next, md_row(header))
+    next = push(next, md_row(separator))
+    next = append_md_rows(next, rows)
+    next = push(next, "")
+    return next
+}
+
+func markdown_code(value) {
+    safe := replace_str(display_path(value), "|", "\\|")
+    mut fence := "`"
+    while contains(safe, fence) == 1 {
+        fence = fence + "`"
+    }
+    return fence + safe + fence
+}
+
+# Clean markdown report.
+export func render_markdown(model, cfg, show_budget) {
+    s := model["summary"]
+    cats := model["categories"]
+    mut out := []
+    out = append_lines(out, [
+        "# ChangeBucket Report",
+        "",
+        "Generated: " + model["generated_at"],
+        "",
+        "Base: " + markdown_code(model["base"]) + "  Head: " + markdown_code(model["head"]),
+        "",
+        "## Summary",
+        ""
+    ])
+    summary := summary_rows(s, markdown_summary_specs())
+    out = append_md_table(out, ["Metric", "Value"], ["---", "---:"], summary)
+
+    if show_budget && model["budget"]["checked"] == true {
+        out = append_lines(out, ["## Budget Result", ""])
+        if model["budget"]["passed"] == true {
+            out = push(out, "Status: **within budget**")
+        } else {
+            out = push(out, "Status: **budget exceeded**")
+        }
+        out = push(out, "")
+        failures := model["budget"]["failures"]
+        if len(failures) > 0 {
+            mut fi := 0
+            while fi < len(failures) {
+                out = push(out, "- " + failures[fi])
+                fi = fi + 1
+            }
+            out = push(out, "")
+        }
+    }
+
+    out = append_lines(out, ["## File Categories", ""])
+    order := category_order()
+    mut category_rows := []
+    mut ci := 0
+    while ci < len(order) {
+        key := order[ci]
+        count := len(cats[key])
+        if count > 0 {
+            category_rows = push(category_rows, [cat_label(key), commas(count)])
+        }
+        ci = ci + 1
+    }
+    out = append_md_table(out, ["Category", "Count"], ["---", "---:"], category_rows)
+
+    largest := top_by_churn(model["files"], 10)
+    out = append_lines(out, ["## Largest Changes", ""])
+    mut largest_rows := []
+    mut li := 0
+    while li < len(largest) {
+        f := largest[li]
+        largest_rows = push(largest_rows, [markdown_code(f["path"]), f["status"], commas(f["additions"]), commas(f["deletions"]), commas(f["churn"])])
+        li = li + 1
+    }
+    out = append_md_table(out, ["File", "Status", "+", "-", "Churn"], ["---", "---", "---:", "---:", "---:"], largest_rows)
+
+    return join(out, "\n")
+}

package/bundled/components/changebucket/src/util.kujo

@@ -0,0 +1,62 @@
+# ChangeBucket :: util
+#
+# Small, dependency-free helpers shared across the tool: timestamps, number
+# formatting, padding for tables, and tiny predicate helpers. Kept deliberately
+# boring so the rest of the codebase can rely on it without surprises.
+
+# Thousands-separated decimal string for an integer, e.g. 1280 -> "1,280".
+# Negative numbers are handled; the sign is preserved.
+export func commas(n) {
+    neg := n < 0
+    mut s := to_string(n)
+    if neg {
+        s = substring(s, 1, len(s))
+    }
+    mut out := ""
+    mut count := 0
+    mut i := len(s) - 1
+    while i >= 0 {
+        out = substring(s, i, i + 1) + out
+        count = count + 1
+        if count == 3 && i > 0 {
+            out = "," + out
+            count = 0
+        }
+        i = i - 1
+    }
+    if neg {
+        out = "-" + out
+    }
+    return out
+}
+
+# Truthiness for the 1/0 predicate builtins (contains/has_key/...).
+export func truthy(flag) {
+    return flag == 1 || flag == true
+}
+
+# True if any element of `arr` equals `value`.
+export func includes(arr, value) {
+    for item in arr {
+        if item == value {
+            return true
+        }
+    }
+    return false
+}
+
+# The basename (last path segment) of a slash-separated path.
+export func basename(path) {
+    parts := split(path, "/")
+    return parts[len(parts) - 1]
+}
+
+# Keep terminal/markdown reports one-record-per-line even when git paths contain
+# legal control characters. JSON output retains the exact original path.
+export func display_path(path) {
+    mut out := replace_str(path, "\\", "\\\\")
+    out = replace_str(out, "\r", "\\r")
+    out = replace_str(out, "\n", "\\n")
+    out = replace_str(out, "\t", "\\t")
+    return out
+}

package/bundled/components/context/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Kujolang <contact@kujolang.ai>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.