devkb 0.2.0__py3-none-any.whl
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.
- devkb/__init__.py +11 -0
- devkb/audit.py +173 -0
- devkb/bench/add_packs.py +52 -0
- devkb/bench/cli_tasks.py +105 -0
- devkb/bench/confirm_tasks.py +149 -0
- devkb/bench/module_truth.py +249 -0
- devkb/bench/oco_tasks.py +216 -0
- devkb/bench/pipeline.py +313 -0
- devkb/bench/process_tasks.py +135 -0
- devkb/bench/report.py +74 -0
- devkb/bench/run.py +174 -0
- devkb/bench/truth_check.py +148 -0
- devkb/bench/workflow_report.py +64 -0
- devkb/bench/workflow_run.py +206 -0
- devkb/bench/workflow_tasks.py +227 -0
- devkb/build.py +258 -0
- devkb/build_symbols.py +1394 -0
- devkb/call_recall.py +159 -0
- devkb/cli.py +53 -0
- devkb/coverage.py +155 -0
- devkb/edge_truth.py +272 -0
- devkb/extractors/backlog.py +113 -0
- devkb/extractors/component_subsystem.py +116 -0
- devkb/extractors/configuration.py +267 -0
- devkb/extractors/files_tests.py +220 -0
- devkb/extractors/flows.py +117 -0
- devkb/extractors/lifecycle.py +258 -0
- devkb/extractors/members.py +160 -0
- devkb/extractors/pull_requests.py +271 -0
- devkb/extractors/releases.py +49 -0
- devkb/extractors/source_baseline.py +66 -0
- devkb/extractors/spec_docs.py +220 -0
- devkb/extractors/symbol_tests.py +131 -0
- devkb/extractors/test_inventory.py +38 -0
- devkb/extractors/ticket_similarity.py +193 -0
- devkb/extractors/tickets_git.py +151 -0
- devkb/extractors/warnings.py +230 -0
- devkb/extractors/work_units.py +90 -0
- devkb/github.py +515 -0
- devkb/gitutil.py +16 -0
- devkb/index.py +51 -0
- devkb/init.py +178 -0
- devkb/mcp_server.py +216 -0
- devkb/model.py +221 -0
- devkb/module_file_bridge.py +57 -0
- devkb/ontology.md +178 -0
- devkb/packs.py +462 -0
- devkb/process_api.py +1601 -0
- devkb/project_context.py +191 -0
- devkb/query.py +251 -0
- devkb/service.py +324 -0
- devkb/startup.py +103 -0
- devkb/test_discovery.py +76 -0
- devkb/ts_symbols.py +291 -0
- devkb-0.2.0.dist-info/METADATA +162 -0
- devkb-0.2.0.dist-info/RECORD +61 -0
- devkb-0.2.0.dist-info/WHEEL +5 -0
- devkb-0.2.0.dist-info/entry_points.txt +2 -0
- devkb-0.2.0.dist-info/licenses/LICENSE +202 -0
- devkb-0.2.0.dist-info/licenses/NOTICE +11 -0
- devkb-0.2.0.dist-info/top_level.txt +1 -0
devkb/ontology.md
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# devkb ontology (ADR-SDP-DEVKB-001)
|
|
2
|
+
|
|
3
|
+
Governed node types and edge verbs for the dev-process knowledge graph. Changing
|
|
4
|
+
this file (add/remove/rename a node type or edge verb) requires an Accepted ADR
|
|
5
|
+
(amendment to `ADR-SDP-DEVKB-001`, or a new `ADR-SDP-DEVKB-NNN`) filed **before**
|
|
6
|
+
the implementing PR is merged — see `CLAUDE.md`'s Forbidden Actions.
|
|
7
|
+
|
|
8
|
+
This is a deliberately small, dev-process-specific vocabulary — not a fork of
|
|
9
|
+
OCO's 55-type/21-verb cyber-threat-intel ontology (`ADR-SDP-FACTORY-EXTRACTION-001`
|
|
10
|
+
judged that graph domain-coupled and non-reusable), and not an extension of
|
|
11
|
+
`discovery/`'s 5-type component-architecture graph (`discovery/ontology.md` scopes
|
|
12
|
+
itself to source structure only, by design non-goal to extend).
|
|
13
|
+
|
|
14
|
+
## Node types
|
|
15
|
+
|
|
16
|
+
| Type | Meaning | Natural key | Primary source | Phase |
|
|
17
|
+
|---|---|---|---|---|
|
|
18
|
+
| `Ticket` | one issue | ticket id, e.g. `ODSF-021` | `issues/*.md` filename + body | 1 |
|
|
19
|
+
| `Commit` | one git commit | full 40-char sha | `git log` | 1 |
|
|
20
|
+
| `WorkPackage` | one work package | WP id | `PROJECT_BOARD.md` + `wp-map.json` | 1 |
|
|
21
|
+
| `Milestone` | one milestone | milestone name | `PROJECT_BOARD.md` milestone summary | 1 |
|
|
22
|
+
| `File` | one repo-relative path | path | `git diff-tree`, compliance evidence | 2 |
|
|
23
|
+
| `TestCase` | one test function (ADR-SDP-DEVKB-003; was: only a test referencing a ticket); carries `ticket` when marked | `path:line` | `@pytest.mark.ticket`/grep | 2 |
|
|
24
|
+
| `Warning` | one compliance/gate finding (open or resolved -- see `status`/`resolved_at` properties) | `sha256(rule+detail+evidence)` (widened from `rule+evidence` alone -- some rules' `evidence` is fixed boilerplate, `detail` is what actually varies per violation) | `dev_compliance_monitor.py --json-report` | 3 |
|
|
25
|
+
| `Symbol` | one function/class/method, below `File` granularity | `path::qualified_name` | `ast` decomposition (`devkb/build_symbols.py`, standalone refresh) | BL-3 |
|
|
26
|
+
| `Release` | one git tag | tag name | `git tag --list` | BL-2 |
|
|
27
|
+
| `WorkUnit` | a probable unit of work inferred from same-day/same-author/file-overlap commit clustering -- **never a `Ticket`**, always `source="commit-cluster-inference"`, `confidence=0.5` | `sha256` of member commit shas | `extractors/work_units.py` | BL-6 |
|
|
28
|
+
| `Endpoint` | one API route | `METHOD path` (matches `discovery/`'s own convention) | FastAPI and Odoo `@http.route` decorator AST capture (`devkb/build_symbols.py`; Odoo: ADR-SDP-DEVKB-003) | BL-7 |
|
|
29
|
+
| `Component` | one deployable service, per `12-sys-arch.pdf`'s definition ("implementation of" a Subsystem) | `Service.natural_key`, identical to `discovery/`'s own | mirrors `discovery/`'s already-built `Service` nodes (`.onboarding/graph.json`) | BL-8 |
|
|
30
|
+
| `Subsystem` | one logical grouping a Component realizes | `pms.config.json`'s own `subsystems[].key` | `pms.config.json` directly | BL-8 |
|
|
31
|
+
| `Flow` | one fully-automated call chain from a detected touch point (`endpoint`/`ui_handler`/`scheduled`/`daemon_entry`, see `devkb/SOT.md` Part 5.4) | `flow:<kind>:<start_symbol>` | mechanical BFS over real `CALLS`/`CALLS_API` edges (`extractors/flows.py`) -- never curated | BL-12 |
|
|
32
|
+
| `ErrorSignature` | one statically-detectable error a Symbol's own body can raise or log (**not** the same as `Warning`, which is process/compliance, not source-derived) | `sha256(kind+label+message_template)` | `ast.Raise` and recognized `logger.<level>(...)` calls (`devkb/build_symbols.py`) | BL-9 |
|
|
33
|
+
| `Spec` | one design doc / ADR / onboarding artifact | path | `docs/adr/`, `design/`, `.onboarding/*.md` | BL-13 |
|
|
34
|
+
| `Requirement` | one PMS requirement | `REQ-NNN` | PMS requirements store; ticket `## Trace` `Requirement` row | BL-14 (ADR-SDP-DEVKB-002) |
|
|
35
|
+
| `Evidence` | one evidence record (REA `ev_…` or ODSF `of_…`), `confidence` as recorded, never upgraded | `evidence_id` | evidence packs `.onboarding/evidence/<EVP>/` | BL-14 (ADR-SDP-DEVKB-002) |
|
|
36
|
+
| `Repository` | one registered project's repository, the product's own or a declared member's (ADR-SDP-DEVKB-005) | project code, e.g. `OCO`, `LTCS` | `projects.json` + the product's `pms.config.json` `graph.members` | ODSF-312 |
|
|
37
|
+
| `ConfigKey` | one named setting: an environment variable, or a root `pms.config.json` top-level key (`pms.config.json:<key>`); **its value is never stored**; never prefixed with a member's code | the name | `extractors/configuration.py` | ODSF-312 |
|
|
38
|
+
| `PullRequest` | one pull request (GitHub; GitLab merge requests later). Properties `number`, `title`, `state` (`open`/`merged`/`closed`), `merged_at`, `base`, `head` (branch names; the owner of `owner/branch` is dropped), `labels`, `url`, `merge_style` (`merge`/`squash`/`rebase` when known), `merge_commit`. **Not stored:** description, review comments, author — the login only under `"github": {"authors": true}` | `PR-<number>`; a member repository's key is prefixed `<CODE>:` as for files. One number sequence per repository, so `PR-137` and an issue `GH-137` never both exist | offline: `git log` merge and squash subjects (always on); online: GitHub GraphQL (opt-in), cached in `.devkb/github/` — `extractors/pull_requests.py`, `github.py` | ADR-DEVKB-007 |
|
|
39
|
+
|
|
40
|
+
**Hosted issues are `Ticket` nodes** (ADR-DEVKB-007), natural key `GH-<number>` (member-prefixed as above), `source`
|
|
41
|
+
`github-issues`, so every ticket tool and pack works on them. Properties: `title`, `state`, `state_reason`, `labels`,
|
|
42
|
+
`milestone`, `url`, `created_at`, `closed_at`, and `status` (`OPEN`/`CLOSED`, the field the tools already read); no body,
|
|
43
|
+
no author (login only under `authors`). `ticket_type` is the issue's type where the repository uses issue types
|
|
44
|
+
(upper-cased: `Bug` → `BUG`), else a label (`epic` → `EPIC`, `bug` → `BUG`, `enhancement`/`feature` → `FEATURE`), else
|
|
45
|
+
`ISSUE`; an issue with sub-issues is `EPIC`. An offline closing keyword creates a stub `GH-<n>` with `source`
|
|
46
|
+
`git-closing-keyword`, `ticket_type` `ISSUE` and `unverified: true` (the number might be a pull request) until an online
|
|
47
|
+
build confirms or removes it.
|
|
48
|
+
|
|
49
|
+
`Epic` and `Story` are **not** separate types: they are `Ticket` nodes with `ticket_type` `EPIC` /
|
|
50
|
+
`STORY`, and the names are query aliases for them (ADR-SDP-DEVKB-002 §2), so every existing
|
|
51
|
+
`Ticket` query keeps working.
|
|
52
|
+
|
|
53
|
+
Properties that carry BL-14 (ODSF-230; properties, not types or verbs, so no schema change):
|
|
54
|
+
`Ticket.ticket_type` is the filename type upper-cased (`STORY`, `EPIC`, `BUG`, …) and is what the
|
|
55
|
+
Epic/Story aliases filter on (`devkb/query.py "stories implementing SPEC-ODSF-003"`); a ticket
|
|
56
|
+
without it (a pre-BL-14 graph) answers only to `tickets`. `Spec.spec_id` is the document's
|
|
57
|
+
front-matter `id`, else its filename stem before the first `_`; a Trace `Specification` row
|
|
58
|
+
resolves against it (or the Spec path) and an id shared by two Spec nodes is ambiguous, so it is
|
|
59
|
+
not linked. A Trace `Epic` row yields `CHILD_OF` only from a `STORY` to an `EPIC`. Every BL-14
|
|
60
|
+
reference that does not resolve (unknown epic, spec or evidence id, an `Epic` row that is not
|
|
61
|
+
STORY → EPIC, malformed evidence pack, one evidence id recorded with two confidences) is
|
|
62
|
+
**reported on stderr at build** and produces no edge — never a guess.
|
|
63
|
+
|
|
64
|
+
## Edge verbs
|
|
65
|
+
|
|
66
|
+
| Verb | From → To | Source | Phase |
|
|
67
|
+
|---|---|---|---|
|
|
68
|
+
| `REFERENCES` | Commit → Ticket | `git log --grep=<ticket>` (1.0); **online only**, a commit message `#N` that resolves to a hosted issue — `source` `git-hash-mention`, confidence 0.8. Offline a bare `#N` makes no edge: it cannot be told from a pull request, and a wrong ticket link is worse than none | 1 / ADR-DEVKB-007 |
|
|
69
|
+
| `CAUSED_BY` | Ticket → Ticket | Bug Lineage `caused_by` | 1 |
|
|
70
|
+
| `REGRESSION_OF` | Ticket → Ticket | Bug Lineage `regression_of` | 1 |
|
|
71
|
+
| `DUPLICATE_OF` | Ticket → Ticket | Bug Lineage `duplicate_of` | 1 |
|
|
72
|
+
| `BLOCKS` | Ticket → Ticket | Bug Lineage `blocks` | 1 |
|
|
73
|
+
| `PART_OF` | Ticket → WorkPackage | `wp-map.json` | 1 |
|
|
74
|
+
| `BELONGS_TO` | WorkPackage → Milestone | `PROJECT_BOARD.md` grouping | 1 |
|
|
75
|
+
| `TOUCHES` | Commit → File | `git diff-tree --name-only` | 2 |
|
|
76
|
+
| `TESTED_BY` | File → TestCase | pytest ticket-marker grep | 2 |
|
|
77
|
+
| `FLAGGED_BY` | File → Warning | compliance `evidence` field, only when a real on-disk path is parseable from it (most violations are process-level, not file-level -- see `extractors/warnings.py`) | 3 |
|
|
78
|
+
| `DEFINED_IN` | Symbol → File, or TestCase → File (ADR-SDP-DEVKB-003) | `ast` decomposition | BL-3 |
|
|
79
|
+
| `CALLS` | Symbol → Symbol | `ast.Call`, same-file (0.8) or cross-file via the caller's own import (0.7) -- resolved relative to the repo root first, then to each ancestor directory of the caller's own file (a real per-service src-root import convention, confirmed live against OCO's own `from app.middleware.auth import ...` inside `webapp/backend/`). An import is followed through re-exports (`from pkg import f` where `pkg/__init__.py` holds `from .impl import f`, up to six hops) and through a dotted module path (`pkg.mod.f()` after `import pkg.mod`; `models.flow_runs.f()` after `from app import models`). A call made outside every function has no caller Symbol and is not an edge: see `Symbol.module_callers` below | BL-3 / BL-3b |
|
|
80
|
+
| `TAGS` | Release → Commit | `git log -1 <tag>` | BL-2 |
|
|
81
|
+
| `GROUPS` | WorkUnit → Commit | `extractors/work_units.py` clustering, `confidence=0.5` | BL-6 |
|
|
82
|
+
| `CALLS_API` | Symbol (frontend, TS) → Symbol (backend route handler) | a frontend route-call site (incl. object-literal methods, e.g. `const api = { x: () => get(...) }`) resolved against a real backend `Endpoint`'s route | BL-4b |
|
|
83
|
+
| `PART_OF` *(new usage)* | File → Component | `discovery/`'s own `Module.service` property, promoted to a real edge | BL-8 |
|
|
84
|
+
| `REALIZES` | Component → Subsystem | `pms.config.json`'s `subsystems[].path`, longest-prefix match against the Component's own path -- skipped, not guessed, when nothing matches | BL-8 |
|
|
85
|
+
| `RAISES` | Symbol → ErrorSignature | `ast.Raise`; `HTTPException(status_code=N, ...)` gets `N` extracted onto `ErrorSignature.status_code` when literal, skipped when dynamic | BL-9 |
|
|
86
|
+
| `LOGS` | Symbol → ErrorSignature | `logger.error/warning/critical/exception(...)` calls | BL-9 |
|
|
87
|
+
| `REGISTERED_ON` | Symbol (middleware) → Endpoint (wildcard marker, `* <router_prefix>`) | `app.add_middleware(X)`/`router.add_middleware(X)` call-site detection | BL-10 |
|
|
88
|
+
| `SIMILAR_TO` | Ticket ↔ Ticket | any nonzero overlap of **evidence-bearing** touched files, carrying `shared_file_count`/`overlap_score`/`weighted_score` (`Edge.extra`) -- still no significance threshold at build time; ranking and capping are query-time concerns and `devkb/query.py` now performs them. A file touched by >10% of tickets is bookkeeping rather than subject matter and is excluded from evidence entirely (computed, reported at build; see `ticket_similarity.hub_files`) | BL-11 |
|
|
89
|
+
| `STEP` | Flow → Symbol, `sequence`/weakest-link `confidence` via `Edge.extra` | mechanical BFS over `CALLS`/`CALLS_API` from a detected touch point | BL-12 |
|
|
90
|
+
| `DOCUMENTS` | Spec → Ticket | ADR `Related:` line / bare ticket-id mentions in spec body, only when the ticket is confirmed to exist in the graph. **Narrowed from an earlier `Spec → File\|Ticket` draft** -- `Symbol`/`File` reach a `Spec` via the existing multi-hop path (`Symbol→File→Commit→Ticket→Spec`) instead of a second, more speculative direct edge | BL-13 |
|
|
91
|
+
| `CHILD_OF` | Story (Ticket) → Epic (Ticket) | ticket `## Trace` `Epic` row | BL-14 |
|
|
92
|
+
| `CHILD_OF` *(new source)* | sub-issue (`GH-n`) → parent issue | GitHub sub-issues, online only; `source` `github-sub-issues`, confidence 1.0; a parent in another repository makes no edge | ADR-DEVKB-007 |
|
|
93
|
+
| `DERIVED_FROM` | Ticket → Requirement | ticket `## Trace` `Requirement` row | BL-14 |
|
|
94
|
+
| `IMPLEMENTS` | Ticket → Spec | ticket `## Trace` `Specification` row, resolved to the spec file | BL-14 |
|
|
95
|
+
| `EVIDENCED_BY` | Ticket \| Spec → Evidence | `References` `evidence — <pack>/bundle.json#<id>` or an `## Open Unknowns` evidence id; only when both ends exist | BL-14 |
|
|
96
|
+
| `IN_REPO` | File → Repository | every File of the product and of each member; a member's keys are prefixed `<CODE>:` | ODSF-312 |
|
|
97
|
+
| `READS` | Symbol → ConfigKey, or File → ConfigKey at module level | literal `os.environ[...]`, `os.environ.get/setdefault/pop`, `os.getenv`, `"X" in os.environ`; test files excluded; `confidence=0.9` | ODSF-312 |
|
|
98
|
+
| `DECLARES` | File → ConfigKey | `*.env.example`/`.env.template`/`.env.sample` `KEY=` lines, compose `environment:` and `${VAR}`, systemd `Environment=`, Dockerfile `ENV`/`ARG`, root `pms.config.json` keys | ODSF-312 |
|
|
99
|
+
| `DEPLOYS` | File → Component | a compose service (`<file>#<service>`), a systemd unit (`systemd:<unit>`), a Dockerfile (its path); `kind`, `image`, `ports`, `exec` as properties | ODSF-312 |
|
|
100
|
+
| `MERGES` | PullRequest → Commit | the commits the pull request brought in. **Offline** (git alone): a merge commit `Merge pull request #N from <owner>/<branch>` → the merge commit and `git rev-list <merge>^1..<merge>^2` (`source` `git-merge-subject`), a single-parent commit whose subject ends `(#N)` (`git-squash-subject`); confidence 0.9, because a subject is text a person can edit. **Online:** the pull request's commit list and merge commit from the API (`github-pr-commits`), confidence 1.0, which also covers rebase merges; for a merged pull request whose complete list the API returned, an offline edge not in it is removed | ADR-DEVKB-007 |
|
|
101
|
+
| `CLOSES` | PullRequest → Ticket | the issues the pull request closes. **Online:** GitHub's own closing references (`github-closing-reference`), confidence 1.0, to this repository's issues only; they replace every offline edge of that pull request. An issue the record names but the issue listing did not return is a Ticket with `fetched: false`. **Offline:** a closing keyword (`Fixes`/`Closes`/`Resolves #N`) in a commit message of the pull request (`git-closing-keyword`), confidence 0.7, `unverified: true` on the edge, since `#N` might be a pull request (no edge is made when `N` is a known pull request) | ADR-DEVKB-007 |
|
|
102
|
+
|
|
103
|
+
## The pull-request layer (ADR-DEVKB-007)
|
|
104
|
+
|
|
105
|
+
- **Offline is always on** and reads only git (one `git log` pass, over the same window as the commit baseline). A
|
|
106
|
+
repository whose `origin` is not a GitHub host (`github.com`, a host containing `github`, or `"github": {"host": …}`
|
|
107
|
+
in `devkb.json`) gets no new nodes.
|
|
108
|
+
- **Online is opt-in:** `devkb build --github`, or `{"github": {"enabled": true}}` in `devkb.json` (`--no-github`
|
|
109
|
+
overrides it). Authentication from `GITHUB_TOKEN` (`GH_ENTERPRISE_TOKEN` for another host) or the `gh` login; host and
|
|
110
|
+
repository from `origin`. One GraphQL request per 100 pull requests or issues, cached in `.devkb/github/` by each
|
|
111
|
+
item's `updated_at` (a rebuild stops paging at the first item older than the cache). The cache holds only the
|
|
112
|
+
fields above and never leaves the machine.
|
|
113
|
+
- **When GitHub cannot be reached** (no token, offline, rate-limited, unauthorized) the build completes with the offline
|
|
114
|
+
layer plus whatever the cache held, prints what it could not fetch, and records it in `manifest.json` under `github`
|
|
115
|
+
(`status`: `ok`, `partial`, `failed`; `reason`; `not_fetched`; `stale_cache_used`). Every tool reply that shows
|
|
116
|
+
pull-request links then carries a `coverage` with `complete: false`, `github` (the status) and a `note`; links the
|
|
117
|
+
offline layer could not verify are listed in `coverage.unverified`.
|
|
118
|
+
- **Privacy:** the queries never ask for descriptions, comments, reviews or e-mail, and the cache stores a whitelist.
|
|
119
|
+
An author login is requested and stored only with `"github": {"authors": true}`. Without it a commit subject
|
|
120
|
+
`Merge pull request #N from owner/branch` is stored as `… from branch`, since the owner is a login.
|
|
121
|
+
|
|
122
|
+
## Envelope shapes
|
|
123
|
+
|
|
124
|
+
Node (as written to `.devkb/nodes.jsonl`):
|
|
125
|
+
```json
|
|
126
|
+
{"uid": "devkb:ticket:<sha256(\"Ticket:ODSF-021\")[:16]>",
|
|
127
|
+
"type": "Ticket", "natural_key": "ODSF-021", "source": "tickets",
|
|
128
|
+
"properties": {"...": "..."}}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Edge (as written to `.devkb/edges.jsonl`):
|
|
132
|
+
```json
|
|
133
|
+
{"from_uid": "...", "to_uid": "...", "verb": "CAUSED_BY",
|
|
134
|
+
"properties": {"source": "bug-lineage", "confidence": 1.0,
|
|
135
|
+
"evidence_ref": "issues/ODSF-021...md#Bug-Lineage"}}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Every edge carries `source`/`confidence`/`evidence_ref`; some verbs also
|
|
139
|
+
carry verb-specific structured data (`Edge.extra`, e.g. `SIMILAR_TO`'s
|
|
140
|
+
`shared_file_count`/`overlap_score`, `STEP`'s `sequence`) merged into the
|
|
141
|
+
same `properties` bag rather than a separate field — a consumer reads
|
|
142
|
+
`properties` generically either way:
|
|
143
|
+
```json
|
|
144
|
+
{"from_uid": "...", "to_uid": "...", "verb": "SIMILAR_TO",
|
|
145
|
+
"properties": {"source": "file-overlap-inference", "confidence": 1.0,
|
|
146
|
+
"evidence_ref": "2 shared touched files (...)",
|
|
147
|
+
"shared_file_count": 2, "overlap_score": 0.5}}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`uid` is deterministic (`sha256(f"{type}:{natural_key}")[:16]`, prefixed
|
|
151
|
+
`devkb:<type>:`) — see `devkb/model.py::uid_for`. Rebuilds are idempotent and
|
|
152
|
+
never duplicate nodes.
|
|
153
|
+
|
|
154
|
+
## Not governed here: `Symbol.security_signals`
|
|
155
|
+
|
|
156
|
+
A property, not a new node type or edge verb, so it isn't a table row
|
|
157
|
+
above — but worth naming since it's a real, load-bearing concept (BL-14,
|
|
158
|
+
`devkb/SOT.md` Part 5.1a / Part 8 OQ2): a fully-automated `list[str]` of which
|
|
159
|
+
policy/criticality detector fired (`path-keyword:<word>`,
|
|
160
|
+
`registered-as-middleware`, `enforces-authz-boundary`), no hand-maintained
|
|
161
|
+
field anywhere. Computed in the same `devkb/build_symbols.py` pass as
|
|
162
|
+
`RAISES`/`REGISTERED_ON`, since both are its own inputs.
|
|
163
|
+
|
|
164
|
+
## Not governed here: what a call list cannot see (`Symbol` properties)
|
|
165
|
+
|
|
166
|
+
Properties, not node types or verbs, written by `devkb/build_symbols.py` and read by every list answer's `coverage`
|
|
167
|
+
and by the packs:
|
|
168
|
+
|
|
169
|
+
| Property | Meaning |
|
|
170
|
+
|---|---|
|
|
171
|
+
| `unresolved_calls` | call sites under this Symbol's short name that the resolver could not attribute to any Symbol |
|
|
172
|
+
| `unresolved_files` | the files holding them, most calls first, at most 20 |
|
|
173
|
+
| `unresolved_file_count` | how many files hold them in all, so a list cut at 20 (or a pack's 10) never reads as complete |
|
|
174
|
+
| `module_callers` | files that call this Symbol outside any function: at import time (`app_dirs = get_app_dirs()`) or in a class body. A signature change breaks them, so the refactor pack and the `callers` tool list them (`module_level_files`); they are not functions, so no call chain passes through them |
|
|
175
|
+
|
|
176
|
+
When the calls a coverage statement counts are all in files the answer already lists, it says so (`in_listed_files`)
|
|
177
|
+
instead of naming no file.
|
|
178
|
+
|