@cleocode/nexus 2026.10.27 → 2026.11.1-canary.10

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.
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # @cleocode/nexus
2
2
 
3
+ > Part of [CLEO](https://github.com/kryptobaseddev/cleo#readme). Start with the root README; run `cleo <command> --help` for any command.
4
+
3
5
  CLEO project registry and code intelligence — unified nexus package.
4
6
 
5
7
  ## Overview
@@ -0,0 +1,4 @@
1
+ {
2
+ "schema": 2,
3
+ "sourceHash": "07da4ff3db1c416639d36f00678f98310afbc2f9c2c83517b229caa1bdbd2897"
4
+ }
@@ -0,0 +1,126 @@
1
+ /**
2
+ * Bounded SQL extractor for the parse-loop pipeline (T14383).
3
+ *
4
+ * Reads SQL DDL text without a grammar: comments are blanked (offsets and line
5
+ * numbers are kept), statements are split on `;` outside string literals,
6
+ * quoted identifiers, dollar-quoted bodies and `BEGIN … END` / `CASE … END`
7
+ * blocks, and each statement is matched against the DDL forms below.
8
+ *
9
+ * - **Schema objects**: `CREATE TABLE`, `CREATE VIRTUAL TABLE` (e.g. FTS5),
10
+ * `CREATE VIEW`, `CREATE INDEX`. Node ids are `<path>::<sqlKind>:<name>`, so a
11
+ * trigger or index may share a table's name.
12
+ * - **Triggers**: `CREATE TRIGGER`, with the table it fires on and the tables
13
+ * its body writes or reads.
14
+ * - **Constraints**: `PRIMARY KEY`, `UNIQUE`, `CHECK` and `FOREIGN KEY` /
15
+ * `REFERENCES`, inline or table-level, recorded on the table node; a foreign
16
+ * key is also a reference to the table it names.
17
+ * - **Migrations**: `ALTER TABLE` (add/drop/rename column, rename table, add
18
+ * constraint) and `DROP TABLE|VIEW|INDEX|TRIGGER`, recorded as references
19
+ * from the file to the object it changes.
20
+ *
21
+ * The graph has no SQL node kinds yet, so SQL objects use the nearest existing
22
+ * kind and carry the exact SQL kind in `meta.sqlKind`: tables and views are
23
+ * `record`, indexes `property`, triggers `function`. SQL nodes are never
24
+ * registered in the symbol table, so no code call can resolve to them.
25
+ *
26
+ * An unterminated quote or block, or a statement no form matches, is recorded
27
+ * in `problems`; the parse loop then reports the file as partially read.
28
+ *
29
+ * Not extracted: DML statements, column-level types, routines (`CREATE
30
+ * FUNCTION|PROCEDURE`), literal SQL inside executable sources, and dynamic SQL.
31
+ *
32
+ * @task T14383
33
+ * @module pipeline/extractors/sql-extractor
34
+ */
35
+ import type { GraphNode, GraphRelation, GraphRelationType } from '@cleocode/contracts';
36
+ /** SQL object kinds the extractor emits as graph nodes. */
37
+ export type SqlObjectKind = 'table' | 'view' | 'index' | 'trigger';
38
+ /** One table constraint recorded on a table node's `meta.constraints`. */
39
+ export interface SqlConstraint {
40
+ /** Constraint form. */
41
+ type: 'primary-key' | 'unique' | 'check' | 'foreign-key';
42
+ /** Declared constraint name, when the SQL names it. */
43
+ name?: string;
44
+ /** Constrained columns (empty for a table-level CHECK). */
45
+ columns: string[];
46
+ /** Referenced table and columns of a foreign key. */
47
+ references?: {
48
+ table: string;
49
+ columns: string[];
50
+ };
51
+ }
52
+ /**
53
+ * A reference from an extracted node (or the file, for a migration statement)
54
+ * to a table or view named in SQL, resolved by {@link linkSqlReferences}.
55
+ */
56
+ export interface SqlTableReference {
57
+ /** Source node id, or the file path for a migration statement. */
58
+ source: string;
59
+ /** Referenced object name, lower-cased and unqualified. */
60
+ target: string;
61
+ /** Relation emitted once the target resolves. */
62
+ type: Extract<GraphRelationType, 'accesses' | 'queries'>;
63
+ /** Why the reference exists (e.g. `foreign key references`). */
64
+ reason: string;
65
+ }
66
+ /** Everything the extractor read from one SQL file. */
67
+ export interface SqlExtraction {
68
+ /** Repository-relative path of the SQL file. */
69
+ filePath: string;
70
+ /** Table, view, index and trigger nodes, first definition per name wins. */
71
+ nodes: GraphNode[];
72
+ /** References to tables and views, linked after every SQL file is read. */
73
+ references: SqlTableReference[];
74
+ /** `ALTER TABLE … RENAME TO` pairs (lower-cased old → new name). */
75
+ renames: {
76
+ from: string;
77
+ to: string;
78
+ }[];
79
+ /** Statements that are neither recognized DDL nor DML. */
80
+ unrecognizedStatements: number;
81
+ /**
82
+ * Why the extraction is partial: an unterminated quote or block (statement
83
+ * boundaries after it cannot be trusted) or unclassified statements. Empty
84
+ * when every statement was read.
85
+ */
86
+ problems: string[];
87
+ }
88
+ /** Result of linking every SQL file's references into the graph. */
89
+ export interface SqlLinkResult {
90
+ /** References resolved to at least one table or view definition. */
91
+ linked: number;
92
+ /** References whose target no indexed SQL file defines. */
93
+ unresolved: number;
94
+ }
95
+ /**
96
+ * Extract SQL schema objects, triggers, constraints and migration statements.
97
+ *
98
+ * @param filePath - Repository-relative path of the SQL file
99
+ * @param source - The file's text
100
+ * @returns Nodes for the file plus the table references to link across files
101
+ * @example
102
+ * ```ts
103
+ * const sql = extractSql('db/schema.sql', 'CREATE TABLE items (id INTEGER PRIMARY KEY);');
104
+ * sql.nodes[0]?.meta?.['sqlKind']; // 'table'
105
+ * ```
106
+ */
107
+ export declare function extractSql(filePath: string, source: string): SqlExtraction;
108
+ /**
109
+ * Link every SQL file's table references to the table and view nodes the
110
+ * indexed SQL files define. A definition in the referencing file wins; a name
111
+ * defined in exactly one other file links with import-scoped confidence; a
112
+ * name defined in several files links to each at ambiguous confidence.
113
+ * `ALTER TABLE … RENAME TO` makes the new name resolve to the renamed table.
114
+ *
115
+ * @param extractions - Every SQL file's extraction from this run
116
+ * @param graph - Graph that already holds the extracted nodes
117
+ * @returns How many references resolved and how many stayed unlinked
118
+ * @example
119
+ * ```ts
120
+ * const { linked, unresolved } = linkSqlReferences([extractSql('a.sql', sql)], graph);
121
+ * ```
122
+ */
123
+ export declare function linkSqlReferences(extractions: Iterable<SqlExtraction>, graph: {
124
+ addRelation(rel: GraphRelation): void;
125
+ }): SqlLinkResult;
126
+ //# sourceMappingURL=sql-extractor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sql-extractor.d.ts","sourceRoot":"","sources":["../../../../src/pipeline/extractors/sql-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EACV,SAAS,EAET,aAAa,EACb,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAG7B,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEnE,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,IAAI,EAAE,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,aAAa,CAAC;IACzD,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,qDAAqD;IACrD,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACnD;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,IAAI,EAAE,OAAO,CAAC,iBAAiB,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;IACzD,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,2EAA2E;IAC3E,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oEAAoE;IACpE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxC,0DAA0D;IAC1D,sBAAsB,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB;AAuVD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAoI1E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,QAAQ,CAAC,aAAa,CAAC,EACpC,KAAK,EAAE;IAAE,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAAA;CAAE,GAC/C,aAAa,CAyCf"}