Using subprojects doesn't seem to work as expected, or we just need more examples

[RobertDeRose]

Let me begin by stating that I genuinely enjoy using hk, but my primary challenge has been comprehending its intended functionality based on the documentation and the visibility into how the Builtins anticipate being invoked or configured.

The remarkable aspect of the Builtins is that I shouldn’t have to customize every one if I’m using the linter/formatter in the standard expected manner. However, I’ve encountered more difficulties than anticipated in achieving this, and without the assistance of my agent, I would likely not have been able to make some tasks work.

This has been the sole advantage of prek. Its legacy pre-commit YAML files provide numerous examples available online. Unfortunately, the hk migrate command seems to be more focused on vendoring than I would have anticipated.

Therefore, I kindly request that we receive more comprehensive and intricate examples, particularly those that align with your envisioned usage of hk in monorepo projects, especially in conjunction with mise and aube.

My current project is a monorepo with a Rust backend and a React Frontend using hk subprojects. I won't go into details of my issues unless you want me to.

[jdx]

Thanks for raising this. I traced through the subproject behavior and found that the existing nested-config example did not explain the composition model clearly enough. In particular, it put the frontend steps only under check while the root also declared pre-commit, leaving that pre-commit hook with no frontend steps.

I opened #1239 to address this. It:

• explains that subprojects merge steps into the root hook with the same name; check steps do not automatically run in pre-commit or fix
• makes the root config responsible for hook-wide behavior such as fix, stash, stage, and report
• adds a complete React frontend + Rust backend example using mise monorepo config roots and per-directory environments
• shows how to invoke aube-managed local ESLint/Prettier binaries with an argv-list prefix
• clarifies that builtins configure commands but do not install their tools
• documents hk check --all --plan for inspecting the resolved scoped jobs

The existing subproject integration tests pass with and without libgit2, so I did not find a failure in literal directory/glob discovery or basic scoping. There are still known limitations: only one level of subprojects is supported, and templated dir = "{{workspace}}" is not currently subproject-relative.

If your failure differs from those cases, please share the root and subproject hk.pkl files, relevant mise.toml files, the command you ran, and its verbose output. That should let us turn any remaining behavior problem into a focused fix.

AI-assisted — Tool: Codex; model: openai/gpt-5; version: unavailable.

[jdx]

only one level of subprojects is supported

i could maybe be convinced to improve this, but there are obvious performance costs to doing so

[RobertDeRose]

Thank you, I had my agent review the current subproject feature to see what I was misunderstanding, and it said the following:

I reviewed the source and reproduced the root failure. The key point:

│ subprojects is a root-config merge feature, not recursive project discovery.

What hk actually does

From the repo root:

1. Config::find_project_config() loads the nearest hk.pkl: root hk.pkl.
2. load_subprojects() finds ui/hk.pkl.
3. merge_subproject("ui", ...) rewrites child steps:
   • tsc → ui:tsc
   • biome → ui:biome
   • dir = "ui"
   • globs are scoped to ui/
4. Commands execute from <repo_root>/ui.

biome works because hk strips ui/ from its file arguments:

  cwd: <repo_root>/ui
  files: src/main.tsx ...
  config: ./biome.json

tsc does not work because Builtins.tsc contains:

  workspace_indicator = "tsconfig.json"
  check = "tsc --noEmit -p {{workspace_indicator}}"

Workspace discovery finds:

  ui/tsconfig.json

hk then runs:

  cwd: <repo_root>/ui
  tsc --noEmit -p ui/tsconfig.json

Therefore TypeScript looks for:

  <repo_root>/ui/ui/tsconfig.json

This is an hk bug/gap: subproject scoping rewrites dir, globs, and names, but does not rewrite {{workspace}} or {{workspace_indicator}}. Other workspace-aware builtins may have the same issue.

So, is there perhaps just a bug as well?

[jdx]

@RobertDeRose Yes—this is a bug, and your agent’s diagnosis is correct. Subproject scoping gives the step a literal working directory and makes {{files}} relative to it, but {{workspace}} and {{workspace_indicator}} remained repository-relative. That caused commands running in ui to receive paths such as ui/tsconfig.json and resolve them as ui/ui/tsconfig.json.

I opened #1242 to fix this centrally. Workspace template paths used by commands are now relative to a literal step working directory, while the repository-relative context used to render templated dir settings is preserved. The PR adds unit coverage and a Bats regression that executes a workspace-aware step from a subproject with both git backends.

Thanks for following up with the concrete reproduction—it exposed a case that the existing subproject tests and my earlier --plan validation did not exercise.

AI-assisted — Tool: Codex; model: openai/gpt-5; version: unavailable.