@c4a/extract-ts 0.5.35-beta.1 → 0.5.36-beta.1

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 (2) hide show
  1. package/README.md +95 -31
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,50 +1,104 @@
1
1
  # @c4a/extract-ts
2
2
 
3
- TypeScript/TSX extraction plugin for C4A. Implements the `ExtractionPlugin` protocol from `@c4a/extract`.
3
+ TypeScript/TSX extraction plugin for C4A. It implements the `ExtractionPlugin` protocol from `@c4a/extract` and is the default plugin used by `context capture --code` for npm-style packages.
4
4
 
5
- ## Role in the monorepo
5
+ ## Role in the Monorepo
6
6
 
7
- Parses TypeScript/TSX projects: detects package entries from `package.json`, traces re-export chains via Tree-sitter AST, and produces `ExtractionResult` v2 with `SymbolInfo[]` + `RelationInfo[]`.
7
+ `@c4a/extract-ts` handles TypeScript package entry detection and AST extraction. It does not write `.context` files directly; `@c4a/extract` runs the plugin and `@c4a/context-cli` persists the resulting raw code snapshot.
8
8
 
9
- **Depends on:** `extract` (protocol + parser), `web-tree-sitter`
10
- **Depended on by:** `daemon`
9
+ **Depends on:** `@c4a/extract`, `web-tree-sitter`
11
10
 
12
- ## What it does
11
+ **Used by:** `@c4a/context-cli`, `@c4a/daemon`, E2E tests
13
12
 
14
- ### Layer 0: Entry detection (`detectEntries`)
13
+ ## Current Extraction Coverage
15
14
 
16
- - Parses `package.json` fields: `exports` (with condition mapping), `main`, `bin`, `workspaces`
17
- - Maps `dist/` paths back to `src/` (e.g., `dist/index.js` -> `src/index.ts`)
18
- - Determines package kind: `lib` / `cli` / `app` / `service`
19
- - Recursively detects monorepo sub-packages via `workspaces` globs
15
+ ### Entry Detection
20
16
 
21
- ### Layer 1: Symbol extraction (`extractSymbols`)
17
+ `detectEntries()` reads `package.json` and supports:
22
18
 
23
- - Traces re-export chains from entry files (`export * from`, `export { A } from`, `export function/class/type`)
24
- - Handles circular re-exports (cycle detection via `inFlight` set)
25
- - Extracts symbols: function, class, interface, type, enum, variable, component, hook
26
- - Extracts class/interface members (props, methods) as nested `SymbolInfo`
27
- - Marks visibility: `exported` (reachable from entry) vs `internal`
28
- - Extracts relations: `imports`, `imports_type`, `extends`, `implements`, `param_type`, `return_type`, `of_type`
29
- - All relations: `grounding=code`, `source=ast`, `confidence=1.0`
19
+ - `exports` maps, including conditional `import`, `default`, and `main` targets
20
+ - `main`
21
+ - `bin`
22
+ - `workspaces` globs ending in `/*`
23
+ - `dist/` to `src/` source-path fallback through `resolveEntrySourcePath()`
24
+ - package kind classification: `lib`, `cli`, or `service`
25
+ - package version propagation into `ExtractionResult.package.version`
30
26
 
31
- ## Key exports
27
+ Entry files are returned as module-relative paths. The repository runner later prefixes them to repo-relative paths in raw snapshots.
32
28
 
33
- - `TypeScriptPlugin` — the plugin class, implements `ExtractionPlugin`
29
+ ### Symbol Extraction
34
30
 
35
- ## Internal modules
31
+ `extractSymbols()` starts from detected entry files, traces exports, and marks reachable declarations as `exported`.
36
32
 
37
- | File | Purpose |
38
- |------|---------|
39
- | `plugin.ts` | Plugin class, wires detectEntries + extractSymbols |
40
- | `entryDetector.ts` | package.json parsing, exports condition mapping, dist->src, workspaces |
41
- | `symbolExtractor.ts` | Tree-sitter AST extraction, symbol/relation collection |
42
- | `exportTracer.ts` | Re-export chain tracing with cycle detection |
43
- | `pathUtils.ts` | Module path resolution, relative import handling |
33
+ It currently extracts:
34
+
35
+ - functions
36
+ - classes
37
+ - interfaces
38
+ - type aliases
39
+ - enums
40
+ - variables
41
+ - TSX component-like variables
42
+ - hook-like functions by name in downstream projection
43
+ - class/interface/type members as nested symbols
44
+ - JSDoc on declarations and members
45
+ - function params and return types
46
+ - type annotations
47
+ - interface/type object members, including object types nested in union/intersection/parenthesized types
48
+ - string-literal union values
49
+ - component `propsType` by `FC<Props>` style annotations or `{ComponentName}Props` convention
50
+
51
+ It emits relations for:
52
+
53
+ - `imports`
54
+ - `imports_type`
55
+ - `extends`
56
+ - `implements`
57
+ - `param_type`
58
+ - `return_type`
59
+ - `of_type`
60
+
61
+ All emitted relations are code-grounded AST relations with confidence `1`.
62
+
63
+ ### Export Tracing
64
+
65
+ `exportTracer.ts` follows:
66
+
67
+ - local exported declarations
68
+ - `export default <identifier>` when the identifier is locally declared
69
+ - `export * from "./module"`
70
+ - `export { A } from "./module"`
71
+ - aliased export specifiers
72
+ - circular re-export chains through an in-flight guard
73
+
74
+ Only declarations reachable through entries are marked `exported`; other declarations in traced files remain `internal`.
75
+
76
+ ## Contract with Code Projection
77
+
78
+ The plugin returns `ExtractionResult` v2. The `@c4a/extract` runner turns that into raw snapshot rows:
79
+
80
+ - `packages.jsonl` receives package name/kind/language/version and package description when present.
81
+ - `symbols.jsonl` receives flattened symbol rows with `symbol_id`, `package_name`, and `module_path`.
82
+ - `edges.jsonl` receives relation rows with package/module/version/hash metadata.
83
+ - `digests.jsonl` receives versioned module digest rows.
84
+
85
+ `context compile --code` consumes those rows to build package/category/symbol Nodes. The important projection inputs are:
86
+
87
+ - stable package names and versions
88
+ - stable exported symbol names
89
+ - useful `kind` values (`component`, `function`, `type`, `interface`, etc.)
90
+ - accurate visibility
91
+ - source file and line ranges
92
+ - relation `from` / `to` values
93
+ - JSDoc and type/member metadata
94
+
95
+ Obsidian Render reads compiled Markdown and graph YAML after projection; it does not read `@c4a/extract-ts` output directly.
44
96
 
45
97
  ## Usage
46
98
 
47
- ```typescript
99
+ Manual registry usage:
100
+
101
+ ```ts
48
102
  import { ExtractionPluginRegistry } from "@c4a/extract";
49
103
  import { TypeScriptPlugin } from "@c4a/extract-ts";
50
104
 
@@ -52,7 +106,17 @@ const registry = new ExtractionPluginRegistry();
52
106
  registry.register(new TypeScriptPlugin());
53
107
  ```
54
108
 
55
- The daemon registers this plugin statically on startup. No configuration needed.
109
+ Runner usage normally goes through `context capture --code`; agents should not hand-build runner input or raw snapshots.
110
+
111
+ ## Internal Modules
112
+
113
+ | File | Purpose |
114
+ |---|---|
115
+ | `plugin.ts` | Plugin class; stores package info from `detectEntries()` for `extractSymbols()` |
116
+ | `entryDetector.ts` | `package.json` parsing, entry target collection, workspace package detection |
117
+ | `symbolExtractor.ts` | Tree-sitter AST extraction, symbol/member/relation collection |
118
+ | `exportTracer.ts` | Re-export tracing and exported/internal split |
119
+ | `pathUtils.ts` | Source-path and relative import resolution |
56
120
 
57
121
  ## Development
58
122
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@c4a/extract-ts",
3
- "version": "0.5.35-beta.1",
3
+ "version": "0.5.36-beta.1",
4
4
  "type": "module",
5
5
  "dependencies": {
6
6
  "web-tree-sitter": "^0.20.8"