edify-agents-cli 0.3.0__tar.gz → 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (136) hide show
  1. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/.gitignore +4 -0
  2. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/CHANGELOG.md +19 -0
  3. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/INSTALL.md +1 -1
  4. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/PKG-INFO +1 -1
  5. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/manifest.md +1 -1
  6. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/__init__.py +1 -1
  7. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/cli.py +11 -4
  8. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/extract.py +69 -18
  9. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/insight.py +31 -14
  10. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/queries.py +25 -2
  11. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/store.py +94 -2
  12. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_cli.py +11 -0
  13. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_graph_paging.py +56 -0
  14. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_self.py +1 -2
  15. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/LICENSE +0 -0
  16. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/README.md +0 -0
  17. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/commands/plan.md +0 -0
  18. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/commands/spec.md +0 -0
  19. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/commands/tasks.md +0 -0
  20. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/commands/verify.md +0 -0
  21. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/formats/plan.example.md +0 -0
  22. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/formats/plan.format.md +0 -0
  23. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/formats/spec.example.md +0 -0
  24. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/formats/spec.format.md +0 -0
  25. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/formats/tasks.example.md +0 -0
  26. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/formats/tasks.format.md +0 -0
  27. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/harvest/harvest.md +0 -0
  28. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/harvest/sources.md +0 -0
  29. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/harvest/vocab.md +0 -0
  30. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/mcp/default-registry.md +0 -0
  31. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/adversary.md +0 -0
  32. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/debugger.md +0 -0
  33. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/implementer-general.md +0 -0
  34. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/implementer-go.md +0 -0
  35. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/implementer-node.md +0 -0
  36. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/implementer-postgres.md +0 -0
  37. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/implementer-python.md +0 -0
  38. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/implementer-rails.md +0 -0
  39. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/implementer-react.md +0 -0
  40. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/planner.md +0 -0
  41. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/test-writer-node.md +0 -0
  42. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/test-writer-python.md +0 -0
  43. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/skills/verifier.md +0 -0
  44. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/edify/templates/CLAUDE.md +0 -0
  45. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/pyproject.toml +0 -0
  46. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/__main__.py +0 -0
  47. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/_toml.py +0 -0
  48. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/agents.py +0 -0
  49. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/anim.py +0 -0
  50. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/assets.py +0 -0
  51. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/__init__.py +0 -0
  52. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/check_cmd.py +0 -0
  53. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/doctor_cmd.py +0 -0
  54. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/feedback_cmd.py +0 -0
  55. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/governance_cmd.py +0 -0
  56. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/graph_cmd.py +0 -0
  57. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/harvest_cmd.py +0 -0
  58. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/init_cmd.py +0 -0
  59. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/init_new_cmd.py +0 -0
  60. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/license_cmd.py +0 -0
  61. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/mcp_cmd.py +0 -0
  62. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/self_cmd.py +0 -0
  63. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/setup_cmd.py +0 -0
  64. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/skills_cmd.py +0 -0
  65. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/swarm_cmd.py +0 -0
  66. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/commands/upgrade_cmd.py +0 -0
  67. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/context.py +0 -0
  68. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/conventions.py +0 -0
  69. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/detect.py +0 -0
  70. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/distribution.py +0 -0
  71. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/errors.py +0 -0
  72. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/feedback.py +0 -0
  73. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/formats/__init__.py +0 -0
  74. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/formats/check.py +0 -0
  75. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/formats/document.py +0 -0
  76. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/formats/finding.py +0 -0
  77. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/formats/fix.py +0 -0
  78. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/formats/mcp.py +0 -0
  79. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/formats/plan.py +0 -0
  80. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/formats/skill.py +0 -0
  81. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/formats/spec.py +0 -0
  82. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/formats/tasks.py +0 -0
  83. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/governance.py +0 -0
  84. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/__init__.py +0 -0
  85. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/ignore.py +0 -0
  86. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/langs/__init__.py +0 -0
  87. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/langs/ctags.py +0 -0
  88. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/langs/markdown.py +0 -0
  89. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/langs/patterns.py +0 -0
  90. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/langs/python_ast.py +0 -0
  91. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/langs/sqlish.py +0 -0
  92. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/graph/model.py +0 -0
  93. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/harvest/__init__.py +0 -0
  94. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/harvest/ledger.py +0 -0
  95. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/harvest/screen.py +0 -0
  96. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/harvest/sources.py +0 -0
  97. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/host.py +0 -0
  98. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/interview.py +0 -0
  99. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/library.py +0 -0
  100. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/licensing/__init__.py +0 -0
  101. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/licensing/binding.py +0 -0
  102. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/licensing/ed25519.py +0 -0
  103. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/licensing/projects.py +0 -0
  104. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/licensing/revocation.py +0 -0
  105. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/licensing/tier.py +0 -0
  106. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/licensing/token.py +0 -0
  107. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/paths.py +0 -0
  108. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/selfinstall.py +0 -0
  109. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/skills.py +0 -0
  110. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/swarm.py +0 -0
  111. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/tsv.py +0 -0
  112. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/src/edify/ui.py +0 -0
  113. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/conftest.py +0 -0
  114. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_anim.py +0 -0
  115. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_detect.py +0 -0
  116. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_feedback.py +0 -0
  117. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_fix.py +0 -0
  118. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_formats.py +0 -0
  119. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_governance.py +0 -0
  120. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_graph.py +0 -0
  121. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_harvest.py +0 -0
  122. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_host.py +0 -0
  123. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_init_new.py +0 -0
  124. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_insight.py +0 -0
  125. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_library.py +0 -0
  126. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_license_cmd.py +0 -0
  127. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_licensing.py +0 -0
  128. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_mixed_versions.py +0 -0
  129. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_platform.py +0 -0
  130. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_projects_retired.py +0 -0
  131. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_selection.py +0 -0
  132. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_swarm.py +0 -0
  133. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_swarm_handback.py +0 -0
  134. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_swarm_merge.py +0 -0
  135. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_toml.py +0 -0
  136. {edify_agents_cli-0.3.0 → edify_agents_cli-0.3.1}/tests/test_ui.py +0 -0
@@ -33,3 +33,7 @@ edify_deploy.pub
33
33
 
34
34
  # Agent worktrees — each one is its own checkout
35
35
  .claude/worktrees/
36
+
37
+ # Rendered films — regenerate with edify-public-site/assets/motion/*/render*.cjs or ink/render-all.sh;
38
+ # the published copies live in edify-public-site/site/assets/film/.
39
+ edify-public-site/assets/motion/*/out/
@@ -7,6 +7,25 @@ Two contract versions move independently of the CLI version and are recorded in
7
7
  `.edify/graph/meta` and `edify/manifest.md`: `graph-schema` (bumping it rebuilds an
8
8
  existing graph rather than misreading it) and `index-schema`.
9
9
 
10
+ ## 0.3.1
11
+
12
+ Faster on huge repositories, and a smaller repository.
13
+
14
+ - **Point lookups.** `graph build` also writes `edges.rev.tsv` (edges sorted by
15
+ destination). `explain`, `context`, `path`, `dependents` and `references` binary-search
16
+ the two sorted files for the nodes they touch instead of loading every edge — same
17
+ answers, same order. On a 1.76M-line repository: `context` 7.0s → 2.5s, `explain`
18
+ 6.0s → 1.7s, `dependents` / `references` 4.9s → 1.7s.
19
+ - **Parallel extraction.** On trees of 1,500+ files, files are parsed in a process pool;
20
+ results fold back in file order, so the graph is byte-identical to a serial build.
21
+ `EDIFY_JOBS=N` sets the workers, `EDIFY_JOBS=1` forces serial. `graph build` on the same
22
+ repository: 27.7s → 20.3s on four cores (63s in 0.2.1).
23
+ - **CLI.** A command family named with no subcommand (`edify swarm`, `edify graph`, …)
24
+ prints that family's help and exits 2 — nothing ran. `edify version` at a terminal shows
25
+ the once-per-version feedback invitation again; off-terminal it keeps the 18 ms path.
26
+ - `.edify/run/` (spawn MCP configs, local leases) carries its own `*` `.gitignore`, so
27
+ `edify init` never edits yours and `doctor` is green from the start.
28
+
10
29
  ## 0.3.0
11
30
 
12
31
  Built for huge repositories, swarms of agents, and several people on one feature.
@@ -16,7 +16,7 @@ it installs one command, `edify`.
16
16
  ```bash
17
17
  pip install edify-agents-cli
18
18
 
19
- edify version # edify 0.3.0
19
+ edify version # edify 0.3.1
20
20
  ```
21
21
 
22
22
  `pip` installs into whichever Python environment it belongs to. Inside a virtual
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: edify-agents-cli
3
- Version: 0.3.0
3
+ Version: 0.3.1
4
4
  Summary: A harness that makes an AI coding agent work reliably on large codebases: three documents and a map.
5
5
  Project-URL: Homepage, https://github.com/EDIFY-agents/EDIFY
6
6
  Project-URL: Documentation, https://github.com/EDIFY-agents/EDIFY#readme
@@ -2,7 +2,7 @@
2
2
 
3
3
  What this install is, and what it pins. Read by `edify doctor` and `edify upgrade`.
4
4
 
5
- - edify: 0.3.0
5
+ - edify: 0.3.1
6
6
  - library: 0.1.0
7
7
  - graph-schema: 1
8
8
  - index-schema: 1
@@ -7,7 +7,7 @@ queries the graph, resolves skills, and checks formats.
7
7
  It is not the agent runtime and it never wraps a model.
8
8
  """
9
9
 
10
- __version__ = "0.3.0"
10
+ __version__ = "0.3.1"
11
11
 
12
12
  # The on-disk contract version for `.edify/graph/`. Bumping it means an existing
13
13
  # graph is rebuilt rather than misread.
@@ -611,7 +611,9 @@ def main(argv: list[str] | None = None) -> int:
611
611
  if argv == ["--version"]:
612
612
  print(f"edify {__version__}")
613
613
  raise SystemExit(0)
614
- if argv == ["version"]:
614
+ # `edify version` takes the same shortcut except at a real terminal, where the
615
+ # full path runs so the once-per-version feedback invite can still appear.
616
+ if argv == ["version"] and not (sys.stdin.isatty() and sys.stdout.isatty()):
615
617
  print(f"edify {__version__}")
616
618
  return 0
617
619
 
@@ -619,10 +621,15 @@ def main(argv: list[str] | None = None) -> int:
619
621
  args = parser.parse_args(argv)
620
622
 
621
623
  if not getattr(args, "func", None):
622
- # A family named with no subcommand prints that family's help, which is
623
- # more useful than the top-level usage the user has already seen.
624
+ # A family named with no subcommand prints that family's help — more useful
625
+ # than the top-level usage — and exits 2: nothing ran, and a script or an
626
+ # agent has to be able to tell that apart from success.
624
627
  if getattr(args, "command", None) in _FAMILIES:
625
- parser.parse_args([args.command, "--help"])
628
+ try:
629
+ parser.parse_args([args.command, "--help"])
630
+ except SystemExit:
631
+ pass
632
+ return 2
626
633
  print(USAGE)
627
634
  return 0 if getattr(args, "command", None) is None else 2
628
635
 
@@ -73,31 +73,35 @@ def build(
73
73
  extraction.extend(ctags.extract_tree(root, files))
74
74
  result.backend = "ctags"
75
75
 
76
+ # Decide every file's fate first, then parse the ones that need it — in parallel
77
+ # on a large tree. Results are folded back in file order, so a parallel build is
78
+ # byte-identical to a serial one.
79
+ plan: list[tuple[str, str | None, bool]] = [] # (rel, language, parse it)
76
80
  for rel in files:
77
- path = root / rel
78
- language = language_for(path)
79
- file_node = Node(node_id("file", rel, "."), "file", rel, 1, rel)
80
- extraction.nodes.append(file_node)
81
-
81
+ language = language_for(root / rel)
82
+ parse = False
82
83
  if language is None:
83
- continue
84
- if method_for(language) == "none":
84
+ pass
85
+ elif method_for(language) == "none":
85
86
  result.uncovered[language] = result.uncovered.get(language, 0) + 1
86
- continue
87
- if backend == "ctags" and language != "markdown":
87
+ elif backend == "ctags" and language not in ("markdown", "sql"):
88
88
  # The external extractor already covered code. Markdown sections and
89
89
  # SQL tables are ours either way — it does not emit them.
90
- if language != "sql":
91
- result.languages[language] = result.languages.get(language, 0) + 1
92
- continue
93
-
94
- try:
95
- source = path.read_text(encoding="utf-8", errors="replace")
96
- except OSError:
90
+ result.languages[language] = result.languages.get(language, 0) + 1
91
+ else:
92
+ parse = True
93
+ plan.append((rel, language, parse))
94
+
95
+ parsed = _parse_all(root, [(rel, lang) for rel, lang, parse in plan if parse])
96
+ for rel, language, parse in plan:
97
+ extraction.nodes.append(Node(node_id("file", rel, "."), "file", rel, 1, rel))
98
+ if not parse:
99
+ continue
100
+ got = parsed.get(rel)
101
+ if got is None:
97
102
  result.skipped += 1
98
103
  continue
99
-
100
- extraction.extend(extract_file(rel, source, language))
104
+ extraction.extend(got)
101
105
  result.languages[language] = result.languages.get(language, 0) + 1
102
106
 
103
107
  _resolve_packages(root, extraction)
@@ -133,6 +137,53 @@ def build(
133
137
  # ---------------------------------------------------------------------------
134
138
 
135
139
 
140
+ #: Below this many files a process pool costs more than it saves.
141
+ PARALLEL_MIN_FILES = 1500
142
+ _CHUNK = 200
143
+
144
+
145
+ def _jobs() -> int:
146
+ """Worker count: `EDIFY_JOBS` if set (1 = serial), else the CPUs available."""
147
+ raw = os.environ.get("EDIFY_JOBS", "")
148
+ if raw.isdigit() and int(raw) > 0:
149
+ return int(raw)
150
+ try:
151
+ return max(1, len(os.sched_getaffinity(0))) # type: ignore[attr-defined]
152
+ except (AttributeError, OSError):
153
+ return max(1, os.cpu_count() or 1)
154
+
155
+
156
+ def _parse_chunk(root: str, items: list[tuple[str, str]]) -> list[tuple[str, Extraction | None]]:
157
+ """Read and extract a batch of files. Top-level so a worker process can run it."""
158
+ out: list[tuple[str, Extraction | None]] = []
159
+ base = Path(root)
160
+ for rel, language in items:
161
+ try:
162
+ source = (base / rel).read_text(encoding="utf-8", errors="replace")
163
+ except OSError:
164
+ out.append((rel, None))
165
+ continue
166
+ out.append((rel, extract_file(rel, source, language)))
167
+ return out
168
+
169
+
170
+ def _parse_all(root: Path, items: list[tuple[str, str]]) -> dict[str, Extraction | None]:
171
+ jobs = _jobs()
172
+ if jobs > 1 and len(items) >= PARALLEL_MIN_FILES:
173
+ chunks = [items[i : i + _CHUNK] for i in range(0, len(items), _CHUNK)]
174
+ try:
175
+ from concurrent.futures import ProcessPoolExecutor
176
+
177
+ with ProcessPoolExecutor(max_workers=min(jobs, len(chunks))) as pool:
178
+ done: dict[str, Extraction | None] = {}
179
+ for batch in pool.map(_parse_chunk, [str(root)] * len(chunks), chunks):
180
+ done.update(batch)
181
+ return done
182
+ except (OSError, ImportError, RuntimeError, NotImplementedError):
183
+ pass # no process support here (sandbox, frozen binary): parse serially
184
+ return dict(_parse_chunk(str(root), items))
185
+
186
+
136
187
  def _scan_roots(root: Path, subdirs: list[str] | None) -> list[Path]:
137
188
  if not subdirs:
138
189
  return [root]
@@ -28,6 +28,7 @@ COMMUNITY_HEADER = ("file", "community", "label")
28
28
  _HUB_KINDS = ("symbol", "route", "table", "module")
29
29
  _KIND_RANK = {"symbol": 0, "route": 1, "table": 2, "doc-section": 3, "module": 4, "file": 5}
30
30
  _SEEDS = 12
31
+ _FAN_CANDIDATES = 400
31
32
  _SEEDS_PER_FILE = 3
32
33
  _STOP = set(
33
34
  "the a an and or of to in on for with from by at is are be this that it as add fix "
@@ -209,6 +210,18 @@ def fan_in(store: GraphStore) -> Counter:
209
210
  return store.cached("fan_in", build)
210
211
 
211
212
 
213
+ def fan_of(store: GraphStore, ids) -> dict[str, int]:
214
+ """Fan-in for just these nodes: point lookups, unless the edges are loaded anyway."""
215
+ if store._edges is not None or "fan_in" in store._memo:
216
+ full = fan_in(store)
217
+ return {i: full.get(i, 0) for i in ids}
218
+ by_id = store.by_id
219
+ out: dict[str, int] = {}
220
+ for i in ids:
221
+ out[i] = len({by_id[s].file for r, s in store.edges_in(i) if r in CODE_RELATIONS and s in by_id})
222
+ return out
223
+
224
+
212
225
  def hubs(store: GraphStore, limit: int = 20) -> list[tuple[Node, int]]:
213
226
  fan = fan_in(store)
214
227
  by_id = store.by_id
@@ -329,9 +342,14 @@ def context(
329
342
  `offset` page the connected list.
330
343
  """
331
344
  ts = terms(query)
332
- fan = fan_in(store)
333
345
  explicit = {tok.strip("`,;()") for tok in query.split()}
334
- scored = _score(store, ts, explicit, fan)
346
+ scored = _score(store, ts, explicit)
347
+ # The hub bonus is small, so it only needs computing for the leading candidates.
348
+ lead = sorted(scored, key=lambda i: (-scored[i], i))[:_FAN_CANDIDATES]
349
+ fan = fan_of(store, lead)
350
+ for nid in lead:
351
+ bonus = 0.6 * math.log1p(fan[nid])
352
+ scored[nid] += bonus * (0.75 if store.by_id[nid].kind == "module" else 1)
335
353
 
336
354
  ranked = sorted(scored.items(), key=lambda p: (-p[1], _KIND_RANK.get(store.by_id[p[0]].kind, 9), p[0]))
337
355
  seeds: list[tuple[str, float]] = []
@@ -353,20 +371,19 @@ def context(
353
371
 
354
372
  seed_ids = {i for i, _ in seeds}
355
373
  by_id = store.by_id
356
- out_adj, in_adj = store.out_edges, store.in_edges
357
374
  related: dict[str, tuple[float, str]] = {}
358
375
  frontier = list(seeds)
359
376
  for hop in range(max(1, depth)):
360
377
  nxt = []
361
378
  for nid, s in frontier:
362
379
  name = by_id[nid].name
363
- for rel, dst in out_adj.get(nid, ()):
380
+ for rel, dst in store.edges_out(nid):
364
381
  if rel in CODE_RELATIONS and dst not in seed_ids and dst in by_id:
365
382
  score = s * 0.4 / (hop + 1)
366
383
  if score > related.get(dst, (0, ""))[0]:
367
384
  related[dst] = (score, f"{name} --{rel}--> it")
368
385
  nxt.append((dst, score))
369
- for rel, src in in_adj.get(nid, ()):
386
+ for rel, src in store.edges_in(nid):
370
387
  if rel in CODE_RELATIONS and src not in seed_ids and src in by_id:
371
388
  score = s * 0.35 / (hop + 1)
372
389
  if score > related.get(src, (0, ""))[0]:
@@ -379,11 +396,14 @@ def context(
379
396
  ((by_id[k], v[0], v[1]) for k, v in related.items() if by_id[k].kind != "package"),
380
397
  key=lambda p: (-p[1], p[0].file, p[0].line),
381
398
  )
399
+ missing = [n.id for n, _ in seed_nodes if n.id not in fan]
400
+ if missing:
401
+ fan.update(fan_of(store, missing))
382
402
  text = _render(store, query, seed_nodes, rel_nodes, budget, fan, dict(folded), limit, offset)
383
403
  return Slice(seed_nodes, rel_nodes, text, dict(folded))
384
404
 
385
405
 
386
- def _score(store: GraphStore, ts: list[str], explicit: set[str], fan: Counter) -> dict[str, float]:
406
+ def _score(store: GraphStore, ts: list[str], explicit: set[str]) -> dict[str, float]:
387
407
  # Path matches depend only on the file, so they are scored once per file.
388
408
  path_hits: dict[str, int] = {}
389
409
  for f in store.by_file:
@@ -413,7 +433,6 @@ def _score(store: GraphStore, ts: list[str], explicit: set[str], fan: Counter) -
413
433
  elif t in tail:
414
434
  s += 3
415
435
  if s:
416
- s += 0.6 * math.log1p(fan.get(n.id, 0))
417
436
  if kind == "module":
418
437
  s *= 0.75
419
438
  scored[n.id] = s
@@ -505,15 +524,15 @@ def resolve_one(store: GraphStore, name: str) -> Node | None:
505
524
  def explain(store: GraphStore, node: Node, limit: int = 25, offset: int = 0) -> dict[str, object]:
506
525
  """One node's edges, both directions, from the store's indexes — no edge scan."""
507
526
  by_id = store.by_id
508
- incoming = [(by_id[s], r) for r, s in store.in_edges.get(node.id, ()) if s in by_id]
509
- outgoing = [(by_id[d], r) for r, d in store.out_edges.get(node.id, ()) if d in by_id]
527
+ incoming = [(by_id[s], r) for r, s in store.edges_in(node.id) if s in by_id]
528
+ outgoing = [(by_id[d], r) for r, d in store.edges_out(node.id) if d in by_id]
510
529
  c = community_of(store).get(node.file)
511
530
  start = max(0, offset)
512
531
  inc, out = incoming[start:start + limit], outgoing[start:start + limit]
513
532
  return {
514
533
  "node": node,
515
534
  "community": f"{c.id} {c.label}" if c else "-",
516
- "fan_in": fan_in(store).get(node.id, 0),
535
+ "fan_in": fan_of(store, [node.id])[node.id],
517
536
  "incoming": inc,
518
537
  "outgoing": out,
519
538
  "incoming_total": len(incoming),
@@ -524,11 +543,9 @@ def explain(store: GraphStore, node: Node, limit: int = 25, offset: int = 0) ->
524
543
 
525
544
  def path(store: GraphStore, a: Node, b: Node, max_hops: int = 8) -> list[tuple[Node, str, str, Node]] | None:
526
545
  """Shortest undirected path; each hop keeps its real direction and relation."""
527
- out_adj, in_adj = store.out_edges, store.in_edges
528
-
529
546
  def around(cur: str) -> list[tuple[str, str, str]]:
530
- near = [(d, r, "->") for r, d in out_adj.get(cur, ())]
531
- near += [(s, r, "<-") for r, s in in_adj.get(cur, ())]
547
+ near = [(d, r, "->") for r, d in store.edges_out(cur)]
548
+ near += [(s, r, "<-") for r, s in store.edges_in(cur)]
532
549
  return sorted(near)
533
550
 
534
551
  prev: dict[str, tuple[str, str, str]] = {a.id: ("", "", "")}
@@ -206,14 +206,37 @@ def _incoming_ids(store: GraphStore) -> dict[str, set[str]]:
206
206
  return store.cached("incoming_ids", build)
207
207
 
208
208
 
209
+ def _sources(store: GraphStore):
210
+ """id → the ids that reach it, as `_incoming_ids` defines them.
211
+
212
+ With the edges already in memory that is the cached index; otherwise each
213
+ asked-about node is a point lookup on the sorted edge files, so `dependents`
214
+ on a huge graph reads a handful of rows instead of every edge.
215
+ """
216
+ if store._edges is not None or "incoming_ids" in store._memo:
217
+ incoming = _incoming_ids(store)
218
+ return lambda nid: incoming.get(nid, ())
219
+
220
+ by_id = store.by_id
221
+
222
+ def lookup(nid: str) -> set[str]:
223
+ ids = [nid]
224
+ node = by_id.get(nid)
225
+ if node is not None and node.kind in ("file", "module"):
226
+ ids += [n.id for n in store.by_file.get(node.file, ()) if n.kind in ("file", "module") and n.id != nid]
227
+ return {src for i in ids for r, src in store.edges_in(i) if r in CODE_RELATIONS}
228
+
229
+ return lookup
230
+
231
+
209
232
  def _reverse_closure(store: GraphStore, seeds: set[str], depth: int) -> list[Node]:
210
- incoming = _incoming_ids(store)
233
+ sources = _sources(store)
211
234
  seen: set[str] = set()
212
235
  frontier = set(seeds)
213
236
  for _ in range(max(1, depth)):
214
237
  nxt: set[str] = set()
215
238
  for node_id in frontier:
216
- for src in incoming.get(node_id, ()):
239
+ for src in sources(node_id):
217
240
  if src not in seen and src not in seeds:
218
241
  seen.add(src)
219
242
  nxt.add(src)
@@ -8,6 +8,7 @@ is a structural diff of the codebase.
8
8
  from __future__ import annotations
9
9
 
10
10
  import hashlib
11
+ import mmap
11
12
  from pathlib import Path
12
13
  from typing import Callable, Iterable, Sequence, TypeVar
13
14
 
@@ -18,6 +19,7 @@ from ..tsv import read_kv, sha256_file, unescape, write_kv
18
19
  from .model import Edge, Node
19
20
 
20
21
  NODE_HEADER = ("id", "kind", "file", "line", "name", "fingerprint")
22
+ REV_HEADER = ("to", "relation", "from")
21
23
  EDGE_HEADER = ("from", "relation", "to")
22
24
  #: Relations that mean "this code uses that code". `defines`, `documents` and
23
25
  #: `migrates` are structure, not use.
@@ -121,6 +123,50 @@ class GraphStore:
121
123
 
122
124
  return self.cached("directed", build)
123
125
 
126
+ # -- point lookups: one node's edges without loading the rest ----------
127
+
128
+ def edges_out(self, node_id: str) -> list[tuple[str, str]]:
129
+ """[(relation, dst)] for one node, in file order.
130
+
131
+ Served from memory when the edges are already loaded; otherwise a binary
132
+ search over `edges.tsv`, which is sorted by source — so `explain` on a
133
+ million-edge graph reads a few kilobytes instead of the whole file.
134
+ """
135
+ if self._edges is not None or "directed" in self._memo:
136
+ return self.out_edges.get(node_id, [])
137
+ mm = self._mapped(self.layout.edges)
138
+ if mm is None:
139
+ return self.out_edges.get(node_id, [])
140
+ return [(r[1], r[2]) for r in _block(mm, node_id) if len(r) >= 3]
141
+
142
+ def edges_in(self, node_id: str) -> list[tuple[str, str]]:
143
+ """[(relation, src)] for one node, in the same order `in_edges` gives."""
144
+ if self._edges is not None or "directed" in self._memo:
145
+ return self.in_edges.get(node_id, [])
146
+ mm = self._mapped(self.edges_rev_path)
147
+ if mm is None or self.meta.get("edges_rev_sha256", "") == "":
148
+ return self.in_edges.get(node_id, [])
149
+ rows = [(r[2], r[1], r[0]) for r in _block(mm, node_id) if len(r) >= 3]
150
+ rows.sort(key=_line) # edges.tsv order: by the rendered (src, relation, dst) line
151
+ return [(r, s) for s, r, _ in rows]
152
+
153
+ @property
154
+ def edges_rev_path(self) -> Path:
155
+ return self.layout.graph_dir / "edges.rev.tsv"
156
+
157
+ def _mapped(self, path: Path):
158
+ key = "mmap:" + path.name
159
+ if key not in self._memo:
160
+ mm = None
161
+ try:
162
+ with open(path, "rb") as fh:
163
+ if fh.seek(0, 2) > 0:
164
+ mm = mmap.mmap(fh.fileno(), 0, access=mmap.ACCESS_READ)
165
+ except (OSError, ValueError):
166
+ mm = None
167
+ self._memo[key] = mm
168
+ return self._memo[key]
169
+
124
170
  @property
125
171
  def file_edges(self) -> list[tuple[str, str, bool]]:
126
172
  """(src file, dst file, dst is a package) for every cross-file code edge.
@@ -172,8 +218,11 @@ class GraphStore:
172
218
  node_rows = sorted((_line(n.row()), n) for n in seen_nodes.values())
173
219
  edge_rows = sorted((_line(e), e) for e in {Edge(*e) for e in edges})
174
220
 
221
+ self._close_maps()
175
222
  nodes_sha = _write(self.layout.nodes, [r for r, _ in node_rows], NODE_HEADER)
176
223
  edges_sha = _write(self.layout.edges, [r for r, _ in edge_rows], EDGE_HEADER)
224
+ # The same edges sorted by destination, so `edges_in` is a binary search too.
225
+ rev_sha = _write(self.edges_rev_path, sorted(_line((d, r, s)) for _, (s, r, d) in edge_rows), REV_HEADER)
177
226
  full = dict(meta)
178
227
  full.update(
179
228
  {
@@ -182,6 +231,7 @@ class GraphStore:
182
231
  "edges": str(len(edge_rows)),
183
232
  "nodes_sha256": nodes_sha,
184
233
  "edges_sha256": edges_sha,
234
+ "edges_rev_sha256": rev_sha,
185
235
  }
186
236
  )
187
237
  write_kv(self.layout.meta, full)
@@ -190,6 +240,12 @@ class GraphStore:
190
240
  self._memo = {}
191
241
  return full
192
242
 
243
+ def _close_maps(self) -> None:
244
+ for key in [k for k in self._memo if k.startswith("mmap:")]:
245
+ mm = self._memo.pop(key)
246
+ if mm is not None:
247
+ mm.close()
248
+
193
249
  def signature(self) -> str:
194
250
  """Identifies this graph's content; derived files record it to detect staleness."""
195
251
  m = self.meta
@@ -201,7 +257,10 @@ class GraphStore:
201
257
  """Complaints, one line each. Empty means the files match their meta."""
202
258
  problems: list[str] = []
203
259
  meta = self.meta
204
- for path, key in ((self.layout.nodes, "nodes_sha256"), (self.layout.edges, "edges_sha256")):
260
+ pairs = [(self.layout.nodes, "nodes_sha256"), (self.layout.edges, "edges_sha256")]
261
+ if "edges_rev_sha256" in meta:
262
+ pairs.append((self.edges_rev_path, "edges_rev_sha256"))
263
+ for path, key in pairs:
205
264
  recorded = meta.get(key)
206
265
  if not recorded:
207
266
  problems.append(f"{path.name}: no checksum recorded in meta")
@@ -239,7 +298,12 @@ def _esc(value: str) -> str:
239
298
 
240
299
 
241
300
  def _line(row: Sequence[str]) -> str:
242
- return "\t".join([_esc(c) for c in row])
301
+ line = "\t".join(row)
302
+ # One C-level scan instead of four per field: only a row with a backslash,
303
+ # newline, carriage return or an embedded tab needs field-by-field escaping.
304
+ if "\\" in line or "\n" in line or "\r" in line or line.count("\t") != len(row) - 1:
305
+ return "\t".join([_esc(c) for c in row])
306
+ return line
243
307
 
244
308
 
245
309
  def _write(path: Path, lines: list[str], header: Sequence[str]) -> str:
@@ -255,6 +319,34 @@ def write_table(path: Path, rows: Iterable[Sequence[str]], header: Sequence[str]
255
319
  return _write(path, sorted(_line(r) for r in rows), header)
256
320
 
257
321
 
322
+ def _block(mm, key: str) -> list[list[str]]:
323
+ """Rows whose first field is `key`, from a file sorted by rendered line."""
324
+ prefix = (_esc(key) + "\t").encode("utf-8")
325
+ start = mm.find(b"\n") + 1 if mm[:1] == b"#" else 0
326
+ lo, hi, end = start, len(mm), len(mm)
327
+ while lo < hi:
328
+ mid = (lo + hi) // 2
329
+ ls = max(start, mm.rfind(b"\n", start, mid) + 1)
330
+ le = mm.find(b"\n", ls)
331
+ le = end if le == -1 else le
332
+ if mm[ls:le] < prefix:
333
+ lo = le + 1
334
+ else:
335
+ hi = ls
336
+ rows: list[list[str]] = []
337
+ pos = lo
338
+ while pos < end:
339
+ le = mm.find(b"\n", pos)
340
+ le = end if le == -1 else le
341
+ line = mm[pos:le]
342
+ if not line.startswith(prefix):
343
+ break
344
+ text = line.decode("utf-8", errors="replace").rstrip("\r")
345
+ rows.append([unescape(c) for c in text.split("\t")] if "\\" in text else text.split("\t"))
346
+ pos = le + 1
347
+ return rows
348
+
349
+
258
350
  def _read(path: Path) -> list[list[str]]:
259
351
  """Rows of a TSV, comment lines skipped."""
260
352
  if not path.exists():
@@ -434,3 +434,14 @@ def test_doctor_notices_a_skill_that_was_never_mirrored(capsys: pytest.CaptureFi
434
434
  def test_init_makes_the_run_directory_ignore_itself(installed) -> None:
435
435
  marker = installed / ".edify" / "run" / ".gitignore"
436
436
  assert marker.is_file() and marker.read_text(encoding="utf-8").splitlines()[-1] == "*"
437
+
438
+
439
+ @pytest.mark.parametrize("family", ["graph", "swarm", "skills", "mcp", "governance", "license", "self"])
440
+ def test_a_bare_family_prints_its_help_and_exits_2(family, capsys) -> None:
441
+ assert main([family]) == 2
442
+ assert "usage:" in capsys.readouterr().out
443
+
444
+
445
+ def test_version_outside_a_terminal_takes_the_fast_path(capsys) -> None:
446
+ assert main(["version"]) == 0
447
+ assert capsys.readouterr().out.strip().startswith("edify ")
@@ -90,3 +90,59 @@ def test_explain_reads_indexes_and_pages(repo: Path) -> None:
90
90
  scanned_in = [e for e in store.edges if e.dst == node.id]
91
91
  assert info["incoming_total"] == len(scanned_in)
92
92
  assert len(info["incoming"]) == min(1, len(scanned_in))
93
+
94
+
95
+ def test_point_lookups_match_the_in_memory_index(repo) -> None:
96
+ """edges_out/edges_in from the sorted files give exactly what the full load gives."""
97
+ from edify.graph import extract
98
+ from edify.graph.store import GraphStore
99
+ from edify.paths import Layout
100
+
101
+ layout = Layout(repo)
102
+ layout.edify.mkdir(parents=True, exist_ok=True)
103
+ extract.build(layout)
104
+ loaded = GraphStore(layout)
105
+ loaded.edges # force the full load
106
+ lazy = GraphStore(layout)
107
+ ids = [n.id for n in lazy.nodes]
108
+ assert ids
109
+ for i in ids:
110
+ assert lazy.edges_out(i) == loaded.edges_out(i), i
111
+ assert lazy.edges_in(i) == loaded.edges_in(i), i
112
+ assert lazy._edges is None, "point lookups must not load every edge"
113
+ assert lazy.verify_checksums() == []
114
+
115
+
116
+ def test_a_parallel_build_is_byte_identical_to_a_serial_one(repo, monkeypatch) -> None:
117
+ from edify.graph import extract
118
+ from edify.paths import Layout
119
+
120
+ layout = Layout(repo)
121
+ layout.edify.mkdir(parents=True, exist_ok=True)
122
+ monkeypatch.setenv("EDIFY_JOBS", "1")
123
+ extract.build(layout)
124
+ serial = (layout.nodes.read_bytes(), layout.edges.read_bytes())
125
+
126
+ monkeypatch.setenv("EDIFY_JOBS", "2")
127
+ monkeypatch.setattr(extract, "PARALLEL_MIN_FILES", 1)
128
+ monkeypatch.setattr(extract, "_CHUNK", 1)
129
+ extract.build(layout)
130
+ assert (layout.nodes.read_bytes(), layout.edges.read_bytes()) == serial
131
+
132
+
133
+ def test_dependents_by_lookup_match_dependents_from_memory(repo) -> None:
134
+ from edify.graph import extract, queries
135
+ from edify.graph.store import GraphStore
136
+ from edify.paths import Layout
137
+
138
+ layout = Layout(repo)
139
+ layout.edify.mkdir(parents=True, exist_ok=True)
140
+ extract.build(layout)
141
+ names = sorted({n.name for n in GraphStore(layout).nodes})
142
+ for name in names:
143
+ for depth in (1, 3):
144
+ loaded = GraphStore(layout)
145
+ loaded.edges
146
+ lazy = GraphStore(layout)
147
+ assert queries.dependents(lazy, name, depth) == queries.dependents(loaded, name, depth), (name, depth)
148
+ assert lazy._edges is None
@@ -274,6 +274,5 @@ def test_update_does_not_touch_any_repository(
274
274
  def test_self_with_no_subcommand_prints_the_family_help(
275
275
  capsys: pytest.CaptureFixture[str],
276
276
  ) -> None:
277
- with pytest.raises(SystemExit):
278
- main(["self"])
277
+ assert main(["self"]) == 2
279
278
  assert "update" in capsys.readouterr().out