@know-graph/core 0.4.0

package/dist/parsers/java-parser.js

@@ -0,0 +1,321 @@
+import { extractMetadata } from './metadata-extractor.js';
+const JAVA_EXTENSIONS = ['.java'];
+/**
+ * Regex to match JavaDoc comment blocks: /** ... * /
+ */
+const JAVADOC_REGEX = /\/\*\*[\s\S]*?\*\//g;
+/**
+ * Regex to match class or record declarations.
+ */
+const JAVA_CLASS_REGEX = /^(?:public|private|protected)?\s*(?:static\s+)?(?:final\s+)?(?:abstract\s+)?(?:class|record)\s+(\w+)(?:<[^>]*>)?(?:\s+extends\s+\S+)?(?:\s+implements\s+[^{]+)?\s*[({]/;
+/**
+ * Regex to match interface declarations.
+ */
+const JAVA_INTERFACE_REGEX = /^(?:public|private|protected)?\s*(?:static\s+)?interface\s+(\w+)(?:<[^>]*>)?(?:\s+extends\s+[^{]+)?\s*\{/;
+/**
+ * Regex to match enum declarations.
+ */
+const JAVA_ENUM_REGEX = /^(?:public|private|protected)?\s*(?:static\s+)?enum\s+(\w+)(?:\s+implements\s+[^{]+)?\s*\{/;
+/**
+ * Regex to match method declarations inside a class.
+ */
+const JAVA_METHOD_REGEX = /^\s+(?:(?:public|private|protected|static|final|abstract|synchronized|native|default)\s+)*(?:<[^>]*>\s+)?(\w+(?:<[^>]*>)?(?:\[\])*)\s+(\w+)\s*\(([^)]*)\)/;
+/**
+ * Regex to match Java annotations (e.g., @Override, @PostMapping("/api")).
+ */
+const JAVA_ANNOTATION_REGEX = /^\s*@\w+/;
+/**
+ * Regex to match package declarations.
+ */
+const JAVA_PACKAGE_REGEX = /^package\s+([\w.]+)\s*;/;
+function getLineNumber(source, charIndex) {
+    let line = 1;
+    for (let i = 0; i < charIndex && i < source.length; i++) {
+        if (source[i] === '\n') {
+            line++;
+        }
+    }
+    return line;
+}
+function stripJavadoc(raw) {
+    // Remove /** and */
+    const inner = raw.slice(3, -2);
+    // Remove leading * on each line
+    const lines = inner.split('\n').map((line) => line.replace(/^\s*\*\s?/, ''));
+    return lines.join('\n').trim();
+}
+function findAllJavadocBlocks(content) {
+    const results = [];
+    let match;
+    const regex = new RegExp(JAVADOC_REGEX.source, 'g');
+    while ((match = regex.exec(content)) !== null) {
+        const startLine = getLineNumber(content, match.index);
+        const endIndex = match.index + match[0].length;
+        const endLine = getLineNumber(content, endIndex - 1);
+        results.push({
+            content: stripJavadoc(match[0]),
+            startLine,
+            endLine,
+            endIndex,
+        });
+    }
+    return results;
+}
+/**
+ * Get the next non-empty line after the given character index,
+ * skipping Java annotations (@Override, @PostMapping, etc.).
+ * Returns the trimmed line content.
+ */
+function getNextCodeLine(content, afterIndex) {
+    const rest = content.slice(afterIndex);
+    const lines = rest.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        if (JAVA_ANNOTATION_REGEX.test(trimmed))
+            continue;
+        return trimmed;
+    }
+    return '';
+}
+/**
+ * Get the next non-empty line after the given character index,
+ * skipping Java annotations. Returns the raw (unstripped) line.
+ */
+function getNextCodeLineRaw(content, afterIndex) {
+    const rest = content.slice(afterIndex);
+    const lines = rest.split('\n');
+    for (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        if (JAVA_ANNOTATION_REGEX.test(line.trim()))
+            continue;
+        return line;
+    }
+    return '';
+}
+/**
+ * Get the line number of the next non-empty, non-annotation line
+ * after the given character index.
+ */
+function getNextCodeLineNumber(content, afterIndex) {
+    const baseLine = getLineNumber(content, afterIndex);
+    const rest = content.slice(afterIndex);
+    const lines = rest.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i]?.trim() ?? '';
+        if (trimmed === '')
+            continue;
+        if (JAVA_ANNOTATION_REGEX.test(trimmed))
+            continue;
+        return baseLine + i;
+    }
+    return baseLine;
+}
+/**
+ * Get the next non-empty line (without skipping annotations).
+ * Used for checking package declarations.
+ */
+function getNextNonEmptyLine(content, afterIndex) {
+    const rest = content.slice(afterIndex);
+    const lines = rest.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed !== '') {
+            return trimmed;
+        }
+    }
+    return '';
+}
+function isModuleLevelJavadoc(content, startLine) {
+    const lines = content.split('\n');
+    for (let i = 0; i < startLine - 1; i++) {
+        const line = lines[i]?.trim() ?? '';
+        if (line === '' ||
+            line.startsWith('//') ||
+            line.startsWith('/*') ||
+            line.startsWith('*')) {
+            continue;
+        }
+        // Check for package/import declarations - those are fine before module-level javadoc
+        if (line.startsWith('package ') || line.startsWith('import ')) {
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+function findEnclosingClassName(content, lineNumber) {
+    const lines = content.split('\n');
+    const targetLine = lines[lineNumber - 1];
+    if (!targetLine)
+        return undefined;
+    const targetIndent = targetLine.search(/\S/);
+    if (targetIndent <= 0)
+        return undefined;
+    for (let i = lineNumber - 2; i >= 0; i--) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const currentIndent = line.search(/\S/);
+        if (currentIndent === -1)
+            continue;
+        if (currentIndent < targetIndent) {
+            const trimmed = line.trim();
+            const classMatch = trimmed.match(JAVA_CLASS_REGEX);
+            if (classMatch) {
+                return classMatch[1];
+            }
+            const ifaceMatch = trimmed.match(JAVA_INTERFACE_REGEX);
+            if (ifaceMatch) {
+                return ifaceMatch[1];
+            }
+            break;
+        }
+    }
+    return undefined;
+}
+function getModuleName(filePath) {
+    const parts = filePath.split('/');
+    const fileName = parts[parts.length - 1] ?? '';
+    return fileName.replace(/\.java$/, '');
+}
+/**
+ * Build a method signature from a raw line match.
+ * Extracts modifiers, return type, name, and parameters.
+ */
+function buildMethodSignature(rawLine) {
+    const trimmed = rawLine.trim();
+    // Remove opening brace if present
+    const withoutBrace = trimmed.replace(/\s*\{.*$/, '');
+    return withoutBrace;
+}
+export function createJavaParser() {
+    return {
+        name: 'java',
+        supportedExtensions: JAVA_EXTENSIONS,
+        parse(content, filePath) {
+            const javadocBlocks = findAllJavadocBlocks(content);
+            const results = [];
+            for (const javadoc of javadocBlocks) {
+                const extraction = extractMetadata(javadoc.content, javadoc.startLine);
+                if (!extraction.metadata) {
+                    continue;
+                }
+                const metadata = extraction.metadata;
+                const nextLine = getNextCodeLine(content, javadoc.endIndex);
+                const nextLineRaw = getNextCodeLineRaw(content, javadoc.endIndex);
+                const nextLineNumber = getNextCodeLineNumber(content, javadoc.endIndex);
+                // Try to match class or record declaration
+                const classMatch = nextLine.match(JAVA_CLASS_REGEX);
+                if (classMatch) {
+                    results.push({
+                        name: classMatch[1],
+                        filePath,
+                        line: nextLineNumber,
+                        column: 1,
+                        language: 'java',
+                        entityType: metadata.type,
+                        metadata,
+                        rawDocstring: javadoc.content,
+                    });
+                    continue;
+                }
+                // Try to match interface declaration
+                const ifaceMatch = nextLine.match(JAVA_INTERFACE_REGEX);
+                if (ifaceMatch) {
+                    results.push({
+                        name: ifaceMatch[1],
+                        filePath,
+                        line: nextLineNumber,
+                        column: 1,
+                        language: 'java',
+                        entityType: metadata.type,
+                        metadata,
+                        rawDocstring: javadoc.content,
+                    });
+                    continue;
+                }
+                // Try to match enum declaration
+                const enumMatch = nextLine.match(JAVA_ENUM_REGEX);
+                if (enumMatch) {
+                    results.push({
+                        name: enumMatch[1],
+                        filePath,
+                        line: nextLineNumber,
+                        column: 1,
+                        language: 'java',
+                        entityType: metadata.type,
+                        metadata,
+                        rawDocstring: javadoc.content,
+                    });
+                    continue;
+                }
+                // Try to match method declaration (inside a class)
+                const methodMatch = nextLineRaw.match(JAVA_METHOD_REGEX);
+                if (methodMatch) {
+                    const name = methodMatch[2];
+                    const parent = findEnclosingClassName(content, nextLineNumber);
+                    const signature = buildMethodSignature(nextLineRaw);
+                    results.push({
+                        name,
+                        filePath,
+                        line: nextLineNumber,
+                        column: 1,
+                        language: 'java',
+                        entityType: metadata.type,
+                        metadata,
+                        rawDocstring: javadoc.content,
+                        signature,
+                        parent,
+                    });
+                    continue;
+                }
+                // Check for package declaration (module-level)
+                const nextNonEmpty = getNextNonEmptyLine(content, javadoc.endIndex);
+                const packageMatch = nextNonEmpty.match(JAVA_PACKAGE_REGEX);
+                if (packageMatch && isModuleLevelJavadoc(content, javadoc.startLine)) {
+                    results.push({
+                        name: packageMatch[1],
+                        filePath,
+                        line: javadoc.startLine,
+                        column: 1,
+                        language: 'java',
+                        entityType: metadata.type,
+                        metadata,
+                        rawDocstring: javadoc.content,
+                    });
+                    continue;
+                }
+                // Module-level JavaDoc or unrecognized target
+                if (isModuleLevelJavadoc(content, javadoc.startLine)) {
+                    results.push({
+                        name: getModuleName(filePath),
+                        filePath,
+                        line: javadoc.startLine,
+                        column: 1,
+                        language: 'java',
+                        entityType: metadata.type,
+                        metadata,
+                        rawDocstring: javadoc.content,
+                    });
+                }
+                else {
+                    results.push({
+                        name: 'unknown',
+                        filePath,
+                        line: javadoc.startLine,
+                        column: 1,
+                        language: 'java',
+                        entityType: metadata.type,
+                        metadata,
+                        rawDocstring: javadoc.content,
+                    });
+                }
+            }
+            return results;
+        },
+    };
+}
+//# sourceMappingURL=java-parser.js.map

package/dist/parsers/java-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"java-parser.js","sourceRoot":"","sources":["../../src/parsers/java-parser.ts"],"names":[],"mappings":"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"}

package/dist/parsers/metadata-extractor.d.ts

@@ -0,0 +1,25 @@
+import type { CoreMetadata, ExtendedMetadata } from '../types/entity.js';
+export interface ExtractionError {
+    readonly message: string;
+    readonly line?: number;
+}
+export interface ExtractionResult {
+    readonly metadata: CoreMetadata | ExtendedMetadata | null;
+    readonly errors: readonly ExtractionError[];
+    readonly rawYaml: string;
+}
+/**
+ * Extract the YAML content following a @knowgraph marker from a comment block.
+ * Returns null if no @knowgraph marker is found.
+ */
+export declare function extractKnowgraphYaml(commentBlock: string): string | null;
+/**
+ * Parse YAML string and validate against knowgraph schemas.
+ * Tries ExtendedMetadataSchema first, then falls back to CoreMetadataSchema.
+ */
+export declare function parseAndValidateMetadata(yamlString: string, baseLineOffset?: number): ExtractionResult;
+/**
+ * Extract and validate @knowgraph metadata from a comment block.
+ */
+export declare function extractMetadata(commentBlock: string, baseLineOffset?: number): ExtractionResult;
+//# sourceMappingURL=metadata-extractor.d.ts.map

package/dist/parsers/metadata-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-extractor.d.ts","sourceRoot":"","sources":["../../src/parsers/metadata-extractor.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAwBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuBxE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,cAAc,GAAE,MAAU,GACzB,gBAAgB,CAkElB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,MAAU,GACzB,gBAAgB,CAWlB"}

package/dist/parsers/metadata-extractor.js

@@ -0,0 +1,137 @@
+/**
+ * @knowgraph
+ * type: module
+ * description: Extracts and validates @knowgraph YAML metadata from comment blocks
+ * owner: knowgraph-core
+ * status: stable
+ * tags: [parser, yaml, extraction, metadata]
+ * context:
+ *   business_goal: Transform raw code comments into structured, validated metadata
+ *   domain: parser-engine
+ */
+import { parse as parseYaml } from 'yaml';
+import { CoreMetadataSchema, ExtendedMetadataSchema } from '../types/entity.js';
+/**
+ * Remove common leading whitespace from all non-empty lines.
+ */
+function dedent(text) {
+    const lines = text.split('\n');
+    const nonEmptyLines = lines.filter((line) => line.trim().length > 0);
+    if (nonEmptyLines.length === 0)
+        return text;
+    const minIndent = Math.min(...nonEmptyLines.map((line) => {
+        const match = line.match(/^(\s*)/);
+        return match ? match[1].length : 0;
+    }));
+    if (minIndent === 0)
+        return text;
+    return lines
+        .map((line) => (line.trim().length > 0 ? line.slice(minIndent) : line))
+        .join('\n');
+}
+/**
+ * Extract the YAML content following a @knowgraph marker from a comment block.
+ * Returns null if no @knowgraph marker is found.
+ */
+export function extractKnowgraphYaml(commentBlock) {
+    const marker = '@knowgraph';
+    const markerIndex = commentBlock.indexOf(marker);
+    if (markerIndex === -1) {
+        return null;
+    }
+    const afterMarker = commentBlock.slice(markerIndex + marker.length);
+    // Strip leading asterisks/hashes from each line (JSDoc or Python comment style)
+    const lines = afterMarker.split('\n').map((line) => {
+        // Remove leading whitespace + * + optional space (JSDoc style)
+        const jsDocStripped = line.replace(/^\s*\*\s?/, '');
+        if (jsDocStripped !== line)
+            return jsDocStripped;
+        // Remove leading whitespace + # + optional space (Python/shell comment style)
+        const hashStripped = line.replace(/^\s*#\s?/, '');
+        if (hashStripped !== line)
+            return hashStripped;
+        return line;
+    });
+    // Dedent to handle indented docstrings (e.g., Python method docstrings)
+    // then trim leading/trailing whitespace
+    return dedent(lines.join('\n')).trim();
+}
+/**
+ * Parse YAML string and validate against knowgraph schemas.
+ * Tries ExtendedMetadataSchema first, then falls back to CoreMetadataSchema.
+ */
+export function parseAndValidateMetadata(yamlString, baseLineOffset = 0) {
+    if (!yamlString.trim()) {
+        return {
+            metadata: null,
+            errors: [{ message: 'Empty YAML content', line: baseLineOffset }],
+            rawYaml: yamlString,
+        };
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(yamlString);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Invalid YAML';
+        return {
+            metadata: null,
+            errors: [
+                { message: `YAML parse error: ${message}`, line: baseLineOffset },
+            ],
+            rawYaml: yamlString,
+        };
+    }
+    if (parsed === null || parsed === undefined || typeof parsed !== 'object') {
+        return {
+            metadata: null,
+            errors: [
+                { message: 'YAML did not produce an object', line: baseLineOffset },
+            ],
+            rawYaml: yamlString,
+        };
+    }
+    // Try extended schema first (superset of core)
+    const extendedResult = ExtendedMetadataSchema.safeParse(parsed);
+    if (extendedResult.success) {
+        return {
+            metadata: extendedResult.data,
+            errors: [],
+            rawYaml: yamlString,
+        };
+    }
+    // Try core schema
+    const coreResult = CoreMetadataSchema.safeParse(parsed);
+    if (coreResult.success) {
+        return {
+            metadata: coreResult.data,
+            errors: [],
+            rawYaml: yamlString,
+        };
+    }
+    // Both failed; report errors from extended schema (more informative)
+    const errors = extendedResult.error.issues.map((issue) => ({
+        message: `Validation error at ${issue.path.join('.')}: ${issue.message}`,
+        line: baseLineOffset,
+    }));
+    return {
+        metadata: null,
+        errors,
+        rawYaml: yamlString,
+    };
+}
+/**
+ * Extract and validate @knowgraph metadata from a comment block.
+ */
+export function extractMetadata(commentBlock, baseLineOffset = 0) {
+    const yamlContent = extractKnowgraphYaml(commentBlock);
+    if (yamlContent === null) {
+        return {
+            metadata: null,
+            errors: [],
+            rawYaml: '',
+        };
+    }
+    return parseAndValidateMetadata(yamlContent, baseLineOffset);
+}
+//# sourceMappingURL=metadata-extractor.js.map

package/dist/parsers/metadata-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-extractor.js","sourceRoot":"","sources":["../../src/parsers/metadata-extractor.ts"],"names":[],"mappings":"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"}

package/dist/parsers/python-parser.d.ts

@@ -0,0 +1,3 @@
+import type { Parser } from './types.js';
+export declare function createPythonParser(): Parser;
+//# sourceMappingURL=python-parser.d.ts.map

package/dist/parsers/python-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python-parser.d.ts","sourceRoot":"","sources":["../../src/parsers/python-parser.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AA6NzC,wBAAgB,kBAAkB,IAAI,MAAM,CAkE3C"}