@spikedpunch/mast 0.1.0

package/dist/ast/extractors/typescript.d.ts

@@ -0,0 +1,179 @@
+import { type Tree, type SyntaxNode } from '../parser.js';
+import type { LanguageExtractor, FileExtraction, ExtractorOptions } from '../extractor.js';
+import type { Chunk, Language, SymbolRecord, ImportRecord, EdgeRecord, ParamEntry } from '../types.js';
+/**
+ * TypeScript/JavaScript chunk extractor.
+ *
+ * Implements §10.1 chunking strategy and §10.2 signature extraction.
+ * Handles class decomposition (shell + method chunks) and the two-pass
+ * walk for `is_exported` detection. tree-sitter parsing is internal —
+ * callers only see the `LanguageExtractor` contract.
+ */
+export declare class TypeScriptExtractor implements LanguageExtractor {
+    readonly language = "typescript";
+    readonly extensions: readonly [".ts", ".tsx", ".js", ".jsx"];
+    extract(src: string, filePath: string, fileMtime: number, options: ExtractorOptions): FileExtraction;
+    extractChunks(parsedTree: Tree, src: string, filePath: string, fileMtime: number, contextLines: number, chunkSplitThreshold: number): Chunk[];
+    declarationHash(node: SyntaxNode, src: string): string;
+    bodyHash(node: SyntaxNode, src: string): string;
+}
+/**
+ * Synthesise the class_shell content: class declaration header + member
+ * signatures (TSDoc + signature line, no bodies) + closing brace.
+ */
+export declare function synthesiseClassShell(classNode: SyntaxNode, bodyNode: SyntaxNode | null, src: string): string;
+/**
+ * Extract declaration text up to (not including) the body block.
+ * For interfaces and type aliases the full node is the signature.
+ */
+export declare function extractSignatureText(node: SyntaxNode, src: string): string;
+/** A symbol's declaration as the AST sees it: no body, structured params. */
+export interface ExtractedSignature {
+    /** Qualified `Class.method` for methods; bare name otherwise. */
+    readonly name: string;
+    readonly line: number;
+    readonly signature: string;
+    readonly params: readonly ParamEntry[];
+    readonly returnType: string | null;
+    readonly doc: string | null;
+}
+/**
+ * Extract a body-free signature (plus structured params and return type) for
+ * every top-level symbol and class method in `tree`. Used by `mast_signature`
+ * and `mast_exports` so they report the declaration, not the function body.
+ */
+export declare function extractSignatures(tree: Tree, src: string): ExtractedSignature[];
+export interface NamedReExport {
+    /** Name the barrel exposes (`bar` in `export { foo as bar } from './x'`). */
+    readonly exportedName: string;
+    /** Name in the source module (`foo` above); equals exportedName when unaliased. */
+    readonly sourceName: string;
+    readonly line: number;
+    /** The `from` clause's module specifier (`'./x'` above) — resolved to a real
+     *  file by the caller (`extract()`, which has the import resolver in scope),
+     *  since this pure function has no filesystem access. Carries the file
+     *  evidence a same-named RE_EXPORTS edge needs to resolve correctly. */
+    readonly module: string;
+}
+export interface StarReExport {
+    readonly module: string;
+    readonly line: number;
+}
+/**
+ * Extract `from`-clause re-exports from a file's top level (§10.1).
+ *
+ * - `export { Foo, Bar as Baz } from './x'` → named records (one per specifier).
+ * - `export * from './x'` (incl. `export * as ns from`) → star record; stars
+ *   carry no per-symbol names, so they map to `re_export_files` rows rather
+ *   than symbols/edges.
+ *
+ * Local aliases without `from` are NOT re-exports — they are handled by
+ * `localExportAliases`.
+ */
+export declare function extractReExports(parsedTree: Tree): {
+    named: NamedReExport[];
+    stars: StarReExport[];
+};
+export declare function sha256(text: string): string;
+export declare function chunkId(filePath: string, startLine: number): string;
+/** Determine language from extension. */
+export declare function languageFromExt(ext: string): Language;
+/**
+ * Expand chunk content by `contextLines` around `[startLine, endLine]`.
+ * Returns the expanded content slice; `startLine`/`endLine` in the chunk
+ * record always reflect AST boundaries, not the expanded region.
+ */
+export declare function expandContent(lines: readonly string[], startLine: number, // 1-indexed
+endLine: number, // 1-indexed, inclusive
+contextLines: number): string;
+/**
+ * Derive `SymbolRecord` entries from an already-extracted chunk list.
+ * Skips anonymous chunks (`symbol_name === null`) and raw `block` chunks.
+ */
+export declare function symbolsFromChunks(chunks: readonly Chunk[]): SymbolRecord[];
+/**
+ * Extract import records from the tree-sitter AST.
+ *
+ * Handles named imports (`import { foo } from './bar'`). Side-effect imports
+ * (`import './side-effect'`), default imports, and namespace imports are
+ * recorded with an empty `symbols` array.
+ *
+ * Specifier-to-file resolution (relative probing, tsconfig aliases, workspace
+ * packages) is NOT done here — it needs project context and is applied by
+ * `extract.ts` via the import resolver (§13.7).
+ */
+export declare function extractImports(parsedTree: Tree, _filePath: string): ImportRecord[];
+/**
+ * Extract graph edge records from a parsed tree:
+ *   - IMPLEMENTS  — class → interface (`implements` clause)
+ *   - EXTENDS     — class/interface → its base (`extends` clause)
+ *   - PARENT_OF   — class → its method symbols
+ *   - POTENTIAL_CALL — caller symbol → statically-resolved callee (§10.3.1)
+ *
+ * Edge records use symbol *names*; `insertEdges` resolves them to ids after all
+ * files' symbols are inserted (two-pass requirement). A POTENTIAL_CALL whose
+ * callee name is not a known indexed symbol is dropped there — that is how the
+ * "only a known symbol becomes a verified edge" rule from §10.3 is enforced.
+ *
+ * `src` is the raw source, used to attach the call-site line + context.
+ *
+ * `onCallSite` (D7, Stage 4) is an optional diagnostics seam: when provided,
+ * it is invoked exactly once per `call_expression` node returned by
+ * `collectCalls`, classifying the outcome of resolving that call. It exists
+ * to make the invariant "every visited call yields an edge or a recorded
+ * drop-reason" assertable in tests (`call-oracle.test.ts`); it is not
+ * persisted, configured, or surfaced in any tool response — a future
+ * instrumentation hook (E2's registered corpus measurement), not a shipped
+ * feature. Leaving it `undefined` (the default) costs one `undefined`-check
+ * per call site and zero allocation on the production path.
+ */
+export declare function extractEdges(parsedTree: Tree, _filePath: string, src: string, onCallSite?: (outcome: CallSiteOutcome) => void): EdgeRecord[];
+/**
+ * D7 (Stage 4) closed outcome union for the `onCallSite` diagnostics seam.
+ * Every `call_expression` node `collectCalls` returns is classified into
+ * EXACTLY one of these four buckets by `emitCallEdges` — that totality is
+ * the self-oracle invariant `call-oracle.test.ts` asserts over mast's own
+ * `src/` corpus:
+ *
+ * - `edge_emitted`: `parseCallee` extracted a receiver/method AND
+ *   `LocalTypeEnvironment.resolveCall` linked it — a POTENTIAL_CALL edge
+ *   was pushed.
+ * - `unparseable_callee`: `parseCallee` returned null — the callee shape is
+ *   not a bare identifier or a member-expression whose receiver
+ *   `receiverString` can stringify (e.g. a chained call `getX().m()`, or a
+ *   dynamic/computed receiver `registry['key'].m()`).
+ * - `unresolved_receiver`: the callee parsed to a non-null receiver string
+ *   (`repo`, `this.repo`, `this`, `super`, ...) but `resolveCall` found no
+ *   binding for it — an unannotated local, a DI container lookup, or any
+ *   other §10.3.1 "does NOT catch" receiver shape.
+ * - `bare_call_unresolved`: the callee parsed as a receiver-less call
+ *   (`foo()`) but the name matched neither an import nor a same-file symbol.
+ *
+ * **Boundary**: `collectCalls` does not descend into nested
+ * function/method/class bodies (its own skip-list, see below) — those call
+ * sites are never handed to `parseCallee` at all and are therefore, by
+ * design, outside this invariant. A file with heavy use of inline
+ * `function`-expression callbacks will visit fewer calls than it contains.
+ */
+export type CallSiteOutcome = 'edge_emitted' | 'unparseable_callee' | 'unresolved_receiver' | 'bare_call_unresolved';
+/** Collect call_expression nodes within a body, not descending into nested
+ *  named/anonymous functions, generators, methods, or classes (their bodies
+ *  are their own scope — non-arrow functions also get their own dynamic
+ *  `this`, so a `this.foo()` inside one is never the enclosing class
+ *  instance; F4's `this_method`/`super_method` bindings must not leak in.
+ *  Arrow functions are deliberately NOT in this list — they inherit the
+ *  enclosing scope's `this` and calls inside them must still resolve).
+ *
+ *  Exported (D7, Stage 4) so `call-oracle.test.ts` can independently
+ *  enumerate the same call sites `emitCallEdges` visits, as the ground
+ *  truth for the `onCallSite` accounting invariant — not part of the
+ *  extractor's public tool-facing surface. */
+export declare function collectCalls(bodyNode: SyntaxNode): SyntaxNode[];
+/**
+ * Extract all identifier tokens from chunk content for `identifier_fts`.
+ * Returns a whitespace-separated, deduplicated list of identifier strings.
+ * Uses a word-boundary regex — sufficient for the unicode61 tokeniser's
+ * identifier-boundary separators.
+ */
+export declare function extractIdentifiers(content: string): string;
+//# sourceMappingURL=typescript.d.ts.map

package/dist/ast/extractors/typescript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["../../../src/ast/extractors/typescript.ts"],"names":[],"mappings":"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"}