@titan-design/code-graph 0.10.0 → 0.13.0

package/README.md

@@ -73,19 +73,50 @@ index version 0.14.0:
   first `#`. A top-level declaration's qualified name is its own name
   (`src/a.ts#createThing`). A member or nested declaration is prefixed by its enclosing named
   scopes, joined with `.`: `src/a.ts#Job.run`, `src/a.ts#outer.helper`, and
-  `src/a.ts#handlers.onClick` for a method of `const handlers = {…}`. Anonymous scopes, such
-  as a callback argument or an unbound class expression, add no segment, so ids do not depend
-  on declaration order. One scope binds a name once: a getter/setter pair, a Python property's
+  `src/a.ts#handlers.onClick` for a method of `const handlers = {…}`. An unbound callback
+  argument, object or class expression adds one `<anonymous>` segment, and consecutive
+  anonymous scopes collapse to one, so
+  `src/a.ts#App.<anonymous>.onHash` is a function declared inside a callback in `App`. The
+  segment keeps it apart from a member `App.onHash`, and ids do not depend on declaration
+  order. One scope binds a name once: a getter/setter pair, a Python property's
   accessors, and overloads each share one node. Index versions before 0.14.0 keyed members by
   bare name, so same-named methods in one file collapsed into one node (TP-182).
 - An **external** id is `npm:<package>` (scope-aware) or the `node:` builtin verbatim.
 
-`NodeKind`, `EdgeKind`, and the `role` vocabulary are unchanged. So is the property the DAG
+`NodeKind` and `EdgeKind` are unchanged, and the `role` vocabulary only grew (see
+[File roles](#file-roles)). So is the property the DAG
 check rests on: an import of a workspace package by its published name resolves to that
 package's source file, not to an `npm:` external, by remapping the `dist/*.d.ts` entry
 ts-morph resolves back onto `src/`. That remap needs the target package built, which is why
 `pnpm build` precedes both `pnpm test` and `dag:check`.
 
+## File roles
+
+Every file and module node carries a `role`, one of `ALL_ROLES`: `test`, `fixture`, `story`,
+`lab`, `barrel`, `types`, `config`, `script`, `entry`, `generated` and `source`. The first
+match wins, in this order:
+
+1. `generated`: a `.gitattributes linguist-generated` path or a `*.gen.*`/`generated/` path.
+2. A configured glob from `.codewatch/roles.json` (below).
+3. `test`, then `story` (`*.stories.{js,jsx,ts,tsx}` with an optional `c`/`m`, and `*.mdx`),
+   so a story under `fixtures/` is still a story.
+4. `fixture`, `script`, `entry` (a `#!` shebang), `barrel`, `types`, `config`, else `source`.
+
+`UNIMPORTED_ROLES` lists the roles nothing imports by design (`test`, `fixture`, `story`, `lab`,
+`config`, `script`, `entry`). Dead-module reachability seeds from them plus `barrel`.
+
+`lab` has no built-in rule, since a `lab/` directory name is too generic to guess. A repo
+assigns it, or any other role, with `.codewatch/roles.json`, which maps roles to
+`.gitattributes`-style globs matched against file ids:
+
+```json
+{ "lab": ["packages/ui/src/lab/**"] }
+```
+
+`loadRoleGlobs(repoRoot)` reads that file (an absent file configures nothing, an unknown role
+throws), and `computeRoleHints` passes the result to `annotateRoles` as `roleGlobs`. `story`,
+`lab` and roles.json arrived in index version 0.21.0.
+
 ## Identity across renames
 
 Added in index version 0.15.0 (TP-187). Git rename detection writes `id_alias` rows mapping a
@@ -227,7 +258,14 @@ the file is unreadable.
 The rules engine turns a snapshot into pass/fail against a `check.json`. Seven rule types:
 `metric-max`, `metric-min`, `metric-product-max`, `metric-outlier`, `forbid-import`,
 `layered-deps`, and `no-internal-only-barrels`. Severity defaults to `error`; only new errors
-fail a check.
+fail a check. `layered-deps` takes `excludeRoles`: an import is dropped when its source or
+destination file has an excluded role. `forbid-import` takes `except`: destination patterns
+that `to` matches but the rule allows, such as one sanctioned entry file.
+
+Validation rejects a rule whose `severity` is anything but `error` or `warning`, whose `kind`
+is not a node kind (`package`, `module`, `file`, `symbol`, `external`), or whose `exclude` is
+not an array of strings. Each of those mistakes used to load silently and disable the rule:
+`"Error"` counted as a warning, `"files"` matched no node, and a string `exclude` was dropped.
 
 `metric-outlier` takes its threshold from the snapshot instead of the rule:
 `{ "type": "metric-outlier", "id": "long-fn", "metric": "symbol_body_lines", "kind": "symbol", "percentile": 95 }`
@@ -281,6 +319,12 @@ file is dropped from coupling too. `symbolSetHash({ unitId, symbolIds }, footpri
 doc unit's sorted `[symbolId, footprint.hash]` pairs, so it ignores member order and changes when
 a member is added, removed or changed.
 
+`diffFootprints(store, { fromSnapshotId, toSnapshotId, ...options })` compares the footprints of
+two snapshots. From-side ids follow the alias chain first, and a symbol under a moved file follows
+its file, so a move reads as `changed` with `reasons: ["renamed"]` alone when its footprint held.
+Each other change is `added`, `removed`, or `changed` with the differing parts (`signature`,
+`consumers`, `coupling`). `files` rolls the changes up to their declaring files, never to consumers.
+
 `scripts/dag-check-self.mjs` in the repo root runs this repo's DAG check on this engine
 instead of codewatch's CLI.
 
@@ -390,6 +434,80 @@ snapshotSymbolCoupling(store, snapshotId); // symbol pairs co-imported by 2+ fil
 The pure `computePageRank`, `computeRelevance`, `computeSymbolConsumers`, and
 `computeSymbolCoupling` take node and edge arrays instead of a store.
 
+### The `./analysis` subpath
+
+`@titan-design/code-graph/analysis` re-exports the report, dashboard, and package-architecture
+derivations below without the root's ts-morph, tree-sitter, and SQLite, so a browser bundle
+can import it. `analysis/graph-report-browser-safe.test.ts` keeps its whole import closure
+free of packages and Node builtins, and fails if the barrel re-exports a module it does not
+check. Symbol coupling is not on it: `symbol-coupling.ts` still reaches `node:path`.
+
+### Dashboard derivations
+
+Ported with TP-918 from codewatch's `graph dashboard`, unchanged apart from import paths. All
+are pure functions over rows the caller has already read, so they run in a browser:
+
+- `collectNodeMetrics` folds metric rows into per-node `NodeMetrics`; `collectSymbolUtil`
+  pairs symbol nodes with their utilization; `buildNodeMetrics`, `buildCentralFiles`,
+  `buildHotExports`, and `buildBlastRadius` shape them for the files a `GraphReportResult`
+  references (`referencedNodes`).
+- `buildSymbolCouplingPayload` caps `computeSymbolCoupling` and `computeSymbolConsumers`
+  into co-imported pairs and per-file consumer groups.
+- `classifyCoupling` marks a co-changed pair hidden, expected, or unindexed against a
+  `SnapshotContext`; build its `linkedPairs` with `pairKey`.
+- `computeHealth` sums four capped penalties into a score out of 100 with its breakdown.
+  Each component has a stable `key` and its `cap`. An optional second argument weighs
+  them the caller's way; `DEFAULT_HEALTH_WEIGHTS` is the dashboard's.
+
+### Context dossier and bundle
+
+Ported with TP-1454 from codewatch's `graph context`, unchanged apart from import paths. All
+three are deterministic projections of rows the caller has already read; no LLM is involved.
+
+- `buildContextDossier(input)` shapes one file or symbol into a `ContextDossier`: metrics,
+  churn, centrality, ownership, consumers split into source and test files, coupling
+  partners, and blast radius. A file target lists its symbols, exports first, each with an
+  `importance` that splits the file's centrality by utilization share. The record carries
+  `schemaVersion` (`CONTEXT_SCHEMA_VERSION`) so a store can invalidate old records.
+- `renderContextMarkdown(dossier)` renders the same facts as markdown.
+- `buildContextBundle(input)` wraps a dossier with the source text of the target's span (read
+  from `repoRoot`, so this one touches the filesystem), its `references` and `imports` edges as
+  explicit callers, dependencies, and coupling partners, and its `coverage_pct`. Pass
+  `relevanceByFile` (from `computeRelevance`) and `targetFileId` to order edges by relevance
+  to the target instead of by weight. `renderBundleText(bundle)` concatenates it for an
+  embedder or an LLM.
+
+### Unused exports and dead modules
+
+Ported with TP-1467 from codewatch's `graph report`, unchanged apart from import paths. Both
+are leads, not verdicts, and both drop files that `keepNode` rejects:
+
+- `topUnusedExports(symbolNodes, publicApi, ctx, limit)` lists exported symbols whose
+  `utilization` is 0 or absent, ranked internal first, then by `symbol_cognitive`
+  descending. `publicApiFiles(nodes, edges)` builds `publicApi`: the files a `barrel`-role
+  node re-exports one hop away, whose exports may still have npm consumers.
+- `topDeadModules(nodes, edges, ctx, limit)` lists files that a forward walk over `imports`
+  and `re-exports` edges never reaches, ranked by `loc`. The walk starts from files with the
+  role `entry`, `barrel`, `test`, `script`, `config` or `fixture`, and from any
+  `main.{ts,tsx,js,jsx}`.
+
+These differ from `pnpm dead:check`, which reads edges rather than `utilization` and follows
+re-exports transitively from package-manifest entries.
+
+### Growth and untested risks
+
+Ported with TP-1468 from codewatch's `graph report`, unchanged apart from import paths. Both
+take a `ReportContext` and a limit, return `GrowthRiskRow[]` and `UntestedRiskRow[]`, and drop
+files that `keepNode` rejects:
+
+- `topGrowthRisks(ctx, limit)` lists files with a structural scaling smell: loop nesting of
+  depth 2 or more, `recursive_functions`, or `search_in_loop`. It is a heuristic, not a Big-O
+  bound. Ranked by `loop_depth`, then smell count.
+- `topUntestedRisks(ctx, limit)` ranks `hotspot × (1 − coverage_pct / 100)`, where the hotspot
+  score is churn × complexity, after Adam Tornhill and CodeScene. Files with no
+  `coverage_pct` metric or full coverage are left out, so a repo with no coverage overlay
+  gets an empty list.
+
 ### Partition quality
 
 `computePartitionQuality` scores a package partition of the file graph: per-package cohesion,
@@ -409,6 +527,18 @@ invertBuckets(fileByPackage); // file id -> package id, skipping the "" unassign
 re-exports, transitively. It over-attributes: one import of one name through a barrel becomes
 one edge per re-export target, which is why it is off by default.
 
+### Package architecture
+
+Ported with TP-917 from codewatch's `graph arch`, unchanged apart from import paths.
+`computeArch` aggregates a snapshot's file edges into package-to-package counts over a list
+of `PackageRoot`s the caller supplies (codewatch detects them from `package.json` files; that
+walk stays in codewatch). It drops test and fixture files, honours `exclude`, `excludeRole`,
+`includeExternal` (one `EXTERNAL_BUCKET` node), and `minEdges`, and with `depth: "modules"` or
+`maxPackageSize` drills packages over the threshold (`DEFAULT_MAX_PACKAGE_SIZE`, 30 files)
+into sub-directory nodes. `bucketFilesByPackage` assigns file ids by longest package prefix,
+with unmatched files under `""`. `filteredFileIds`, `aggregateEdges`, `toSortedEdges`, and
+`packagesReferencedByEdges` are the steps it composes.
+
 ### Pruning snapshots
 
 `planPrune` keeps the most recent `keep` snapshots (default 10) plus every snapshot whose ref

package/dist/analysis/browser.d.ts

@@ -0,0 +1,2 @@
+export { A as ArchEdge, m as ArchPackage, n as ArchResult, o as ArchSubNode, B as BlastRadiusEntry, p as BucketableViolation, q as BusFactorChange, r as BusFactorRow, s as CentralRow, u as ComputeArchInput, v as ComputeDriftInput, w as CouplingClass, x as CouplingDelta, y as CouplingRow, D as DEFAULT_HEALTH_WEIGHTS, z as DEFAULT_MAX_PACKAGE_SIZE, H as DeadModuleRow, J as EXTERNAL_BUCKET, L as GraphReportResult, M as GrowthRiskRow, O as HealthComponent, P as HealthComponentKey, Q as HealthInput, U as HealthWeights, W as HotExport, X as HotspotDelta, Y as HotspotRow, a4 as NewHotspot, f as NodeMetrics, a8 as PackageRoot, a9 as PackageStats, aa as PairCoupling, ac as PartitionQualityInput, ad as PartitionQualityResult, ae as PenaltyWeight, af as ReportContext, ag as ReportContextInput, ah as ReportDrift, ai as SnapshotContext, g as SymbolConsumers, an as SymbolUtil, ao as TestCoverageRow, T as TestSourceLink, ap as UnchangedViolation, aq as UntestedRiskRow, ar as UnusedExportRow, V as ViolationBuckets, at as aggregateEdges, au as bucketFilesByPackage, av as bucketViolations, aw as buildBlastRadius, ax as buildCentralFiles, ay as buildHotExports, az as buildNodeMetrics, aA as buildReportContext, aC as busFactorOf, aD as classifyCoupling, aE as collectNodeMetrics, aF as collectSymbolUtil, aG as computeArch, aH as computeHealth, aI as computePartitionQuality, aJ as computeReportDrift, aK as computeSymbolConsumers, aM as filteredFileIds, b7 as hotspotComplexityOf, aO as hotspotScoreOf, aQ as keepNode, aR as linkTestsToSources, aS as lookupMetric, aT as packagesReferencedByEdges, aU as pairKey, aV as publicApiFiles, aX as referencedNodes, aZ as toSortedEdges, a_ as topBusFactorRisks, a$ as topCentralFiles, b0 as topDeadModules, b1 as topGrowthRisks, b2 as topHotspots, b3 as topTestCoverageRisks, b4 as topUntestedRisks, b5 as topUnusedExports } from '../browser-BBzShneN.js';
+import '../change-coupling-CT3bcZMD.js';

package/dist/analysis/browser.js

@@ -0,0 +1,84 @@
+import {
+  DEFAULT_HEALTH_WEIGHTS,
+  DEFAULT_MAX_PACKAGE_SIZE,
+  EXTERNAL_BUCKET,
+  aggregateEdges,
+  bucketFilesByPackage,
+  bucketViolations,
+  buildBlastRadius,
+  buildCentralFiles,
+  buildHotExports,
+  buildNodeMetrics,
+  buildReportContext,
+  busFactorOf,
+  classifyCoupling,
+  collectNodeMetrics,
+  collectSymbolUtil,
+  computeArch,
+  computeHealth,
+  computePartitionQuality,
+  computeReportDrift,
+  computeSymbolConsumers,
+  filteredFileIds,
+  hotspotComplexityOf,
+  hotspotScoreOf,
+  keepNode,
+  linkTestsToSources,
+  lookupMetric,
+  packagesReferencedByEdges,
+  pairKey,
+  publicApiFiles,
+  referencedNodes,
+  toSortedEdges,
+  topBusFactorRisks,
+  topCentralFiles,
+  topDeadModules,
+  topGrowthRisks,
+  topHotspots,
+  topTestCoverageRisks,
+  topUntestedRisks,
+  topUnusedExports
+} from "../chunk-L5KU543A.js";
+import "../chunk-HIVVDGWE.js";
+export {
+  DEFAULT_HEALTH_WEIGHTS,
+  DEFAULT_MAX_PACKAGE_SIZE,
+  EXTERNAL_BUCKET,
+  aggregateEdges,
+  bucketFilesByPackage,
+  bucketViolations,
+  buildBlastRadius,
+  buildCentralFiles,
+  buildHotExports,
+  buildNodeMetrics,
+  buildReportContext,
+  busFactorOf,
+  classifyCoupling,
+  collectNodeMetrics,
+  collectSymbolUtil,
+  computeArch,
+  computeHealth,
+  computePartitionQuality,
+  computeReportDrift,
+  computeSymbolConsumers,
+  filteredFileIds,
+  hotspotComplexityOf,
+  hotspotScoreOf,
+  keepNode,
+  linkTestsToSources,
+  lookupMetric,
+  packagesReferencedByEdges,
+  pairKey,
+  publicApiFiles,
+  referencedNodes,
+  toSortedEdges,
+  topBusFactorRisks,
+  topCentralFiles,
+  topDeadModules,
+  topGrowthRisks,
+  topHotspots,
+  topTestCoverageRisks,
+  topUntestedRisks,
+  topUnusedExports
+};
+//# sourceMappingURL=browser.js.map

package/dist/analysis/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}