[Query API] Lineage Query (#1080)

* feat(lineage-query): impl of lineage query

* doc(lineage-query): basic message documentation and deprectation

src/documentation/data/server/doc-data-server-messages.ts

@@ -503,10 +503,15 @@ See [above](#message-request-file-analysis) for the general structure of the res
     end
     deactivate  Server
 	`,
-		shortDescription: 'Obtain the lineage of a given slicing criterion.',
+		shortDescription: '([DEPRECATED](${FlowrWikiBaseRef}/Query%20API)) Obtain the lineage of a given slicing criterion.',
 		text:             async(shell: RShell) => {
 			return `
 
+${block({
+		type:    'WARNING',
+		content: `We deprecated the lineage request in favor of the \`lineage\` [Query](${FlowrWikiBaseRef}/Query%20API).`
+	})}
+
 In order to retrieve the lineage of an object, you have to send a file analysis request first. The \`filetoken\` you assign is of use here as you can re-use it to repeatedly retrieve the lineage of the same file.
 Besides that, you will need to add a [criterion](${FlowrWikiBaseRef}/Terminology#slicing-criterion) that specifies the object whose lineage you're interested in.
 

src/documentation/doc-util/doc-query.ts

@@ -147,6 +147,13 @@ export function asciiSummaryOfQueryResult(formatter: OutputFormatter, totalInMs:
 				}))`);
 			}
 			continue;
+		} else if(query === 'lineage') {
+			const out = queryResults as QueryResults<'lineage'>['lineage'];
+			result.push(`Query: ${bold(query, formatter)} (${printAsMs(out['.meta'].timing, 0)})`);
+			for(const [criteria, lineage] of Object.entries(out.lineages)) {
+				result.push(`   ╰ ${criteria}: {${summarizeIdsIfTooLong([...lineage])}}`);
+			}
+			continue;
 		}
 
 		result.push(`Query: ${bold(query, formatter)}`);

src/documentation/print-query-wiki.ts

@@ -20,6 +20,7 @@ import { executeIdMapQuery } from '../queries/catalog/id-map-query/id-map-query-
 import { executeNormalizedAstQuery } from '../queries/catalog/normalized-ast-query/normalized-ast-query-executor';
 import { executeDataflowClusterQuery } from '../queries/catalog/cluster-query/cluster-query-executor';
 import { executeStaticSliceClusterQuery } from '../queries/catalog/static-slice-query/static-slice-query-executor';
+import { executeLineageQuery } from '../queries/catalog/lineage-query/lineage-query-executor';
 
 
 registerQueryDocumentation('call-context', {
@@ -132,6 +133,41 @@ ${
 	}
 });
 
+registerQueryDocumentation('lineage', {
+	name:             'Lineage Query',
+	type:             'active',
+	shortDescription: 'Returns lineage of a criteria.',
+	functionName:     executeLineageQuery.name,
+	functionFile:     '../queries/catalog/lineage-query/lineage-query-executor.ts',
+	buildExplanation: async(shell: RShell) => {
+		const exampleCode = 'x <- 1\nx';
+
+		return `
+This query calculates the _lineage_ of a given slicing criterion. The lineage traces back all parts that the
+respective variables stems from given the reads, definitions, and returns in the dataflow graph.
+
+To understand this, let's start with a simple example query, to get the lineage of the second use of \`x\` in the following code:
+${codeBlock('r', exampleCode)}
+ 
+For this, we use the criterion \`2@x\` (which is the first use of \`x\` in the second line).
+ 
+${
+	await showQuery(shell, exampleCode, [{
+		type:      'lineage',
+		criterion: '2@x'
+	}], { showCode: false })
+}
+
+In this simple scenario, the _lineage_ is equivalent to the slice (and in-fact the complete code). 
+In general the lineage is smaller and makes no executability guarantees. 
+It is just a quick and neither complete nor sound way to get information on where the variable originates from.
+
+This query replaces the old [\`request-lineage\`](${FlowrWikiBaseRef}/Interface#message-request-lineage) message.
+
+		`;
+	}
+});
+
 registerQueryDocumentation('dataflow-cluster', {
 	name:             'Dataflow Cluster Query',
 	type:             'active',

src/queries/catalog/lineage-query/lineage-query-executor.ts

@@ -0,0 +1,25 @@
+import type { BasicQueryData } from '../../query';
+import type {
+	LineageQuery,
+	LineageQueryResult
+} from './lineage-query-format';
+import { log } from '../../../util/log';
+import { getLineage } from '../../../cli/repl/commands/repl-lineage';
+
+export function executeLineageQuery({ graph, ast }: BasicQueryData, queries: readonly LineageQuery[]): LineageQueryResult {
+	const start = Date.now();
+	const result: LineageQueryResult['lineages'] = {};
+	for(const { criterion } of queries) {
+		if(result[criterion]) {
+			log.warn('Duplicate criterion in lineage query:', criterion);
+		}
+		result[criterion] = getLineage(criterion, graph, ast.idMap);
+	}
+
+	return {
+		'.meta': {
+			timing: Date.now() - start
+		},
+		lineages: result
+	};
+}

src/queries/catalog/lineage-query/lineage-query-format.ts

@@ -0,0 +1,16 @@
+import type { BaseQueryFormat, BaseQueryResult } from '../../base-query-format';
+import type { SingleSlicingCriterion } from '../../../slicing/criterion/parse';
+import type { NodeId } from '../../../r-bridge/lang-4.x/ast/model/processing/node-id';
+
+/**
+ * Calculates the lineage of the given criterion.
+ */
+export interface LineageQuery extends BaseQueryFormat {
+	readonly type:      'lineage';
+	readonly criterion: SingleSlicingCriterion;
+}
+
+export interface LineageQueryResult extends BaseQueryResult {
+	/** Maps each criterion to the found lineage, duplicates are ignored. */
+	readonly lineages: Record<SingleSlicingCriterion, Set<NodeId>>;
+}

src/queries/query-schema.ts

@@ -38,14 +38,20 @@ export const StaticSliceQuerySchema = Joi.object({
 	noMagicComments:  Joi.boolean().optional().description('Should the magic comments (force-including lines within the slice) be ignored?')
 }).description('Slice query used to slice the dataflow graph');
 
+export const LineageQuerySchema = Joi.object({
+	type: Joi.string().valid('lineage').required().description('The type of the query.'),
+	id:   Joi.string().required().description('The ID of the node to get the lineage of.')
+}).description('Lineage query used to find the lineage of a node in the dataflow graph');
+
 
 export const SupportedQueriesSchema = Joi.alternatives(
 	CallContextQuerySchema,
 	DataflowQuerySchema,
 	IdMapQuerySchema,
 	NormalizedAstQuerySchema,
 	DataflowClusterQuerySchema,
-	StaticSliceQuerySchema
+	StaticSliceQuerySchema,
+	LineageQuerySchema
 ).description('Supported queries');
 
 export const CompoundQuerySchema = Joi.object({

src/queries/query.ts

@@ -18,8 +18,10 @@ import type { DataflowClusterQuery } from './catalog/cluster-query/cluster-query
 import { executeDataflowClusterQuery } from './catalog/cluster-query/cluster-query-executor';
 import type { StaticSliceQuery } from './catalog/static-slice-query/static-slice-query-format';
 import { executeStaticSliceClusterQuery } from './catalog/static-slice-query/static-slice-query-executor';
+import type { LineageQuery } from './catalog/lineage-query/lineage-query-format';
+import { executeLineageQuery } from './catalog/lineage-query/lineage-query-executor';
 
-export type Query = CallContextQuery | DataflowQuery | NormalizedAstQuery | IdMapQuery | DataflowClusterQuery | StaticSliceQuery;
+export type Query = CallContextQuery | DataflowQuery | NormalizedAstQuery | IdMapQuery | DataflowClusterQuery | StaticSliceQuery | LineageQuery;
 
 export type QueryArgumentsWithType<QueryType extends BaseQueryFormat['type']> = Query & { type: QueryType };
 
@@ -41,7 +43,8 @@ export const SupportedQueries = {
 	'id-map':           executeIdMapQuery,
 	'normalized-ast':   executeNormalizedAstQuery,
 	'dataflow-cluster': executeDataflowClusterQuery,
-	'static-slice':     executeStaticSliceClusterQuery
+	'static-slice':     executeStaticSliceClusterQuery,
+	'lineage':          executeLineageQuery
 } as const satisfies SupportedQueries;
 
 export type SupportedQueryTypes = keyof typeof SupportedQueries;

test/functionality/dataflow/query/lineage-query-tests.ts

@@ -0,0 +1,24 @@
+import { assertQuery } from '../../_helper/query';
+import { label } from '../../_helper/label';
+import { withShell } from '../../_helper/shell';
+import type {
+	LineageQuery,
+	LineageQueryResult
+} from '../../../../src/queries/catalog/lineage-query/lineage-query-format';
+import { getLineage } from '../../../../src/cli/repl/commands/repl-lineage';
+
+describe('Lineage Query', withShell(shell => {
+	function testQuery(name: string, code: string, query: readonly LineageQuery[]) {
+		assertQuery(label(name), shell, code, query, ({ dataflow }) => ({
+			'lineage': {
+				lineages: query.reduce((acc, { criterion }) => {
+					acc[criterion] = getLineage(criterion, dataflow.graph);
+					return acc;
+				}, {} as LineageQueryResult['lineages'])
+			}
+		}));
+	}
+
+	testQuery('Single Expression', 'x + 1', [{ type: 'lineage', criterion: '1@x' }]);
+	testQuery('Multiple Queries', 'x + 1', [{ type: 'lineage', criterion: '1@x' }, { type: 'lineage', criterion: '1@x' }, { type: 'lineage', criterion: '1@x' }]);
+}));