@configdirector/cli 0.8.0-beta.1 → 0.9.0-beta.1

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to `@configdirector/cli` are documented here. The format fol
 
 ## [Unreleased]
 
+## [0.9.0-beta.1] - 2026-10-18
+
+### Added
+
+- `configdirector scan --json` prints, and `scan --upload` sends, a snippet with each direct and indirect reference: its line and the 2 lines before and after it, so the dashboard can show the code around the reference. A snippet stops at the start and end of the file, leaves out line endings, and cuts a line longer than 250 characters to its first 250, listing it in `truncatedLines`. Dynamic references have no snippet, and the text output is unchanged. `schema/scan-output.schema.json` describes the `snippet` field.
+- `--context-lines <number>` sets how many lines before and after each reference the snippet includes, from 0 to 5; `--context-lines 0` includes the reference line alone. `--no-snippets` sends no snippet. Giving both, or a `--context-lines` that is not a whole number from 0 to 5, exits with 2.
+- When the project's Code snippets setting is off, `scan --upload` sends no snippets and ends with `Code snippets were not sent: this project does not store them.` `scan` without `--upload` still prints them with `--json`.
+
 ## [0.8.0-beta.1] - 2026-10-18
 
 ### Added

package/README.md

@@ -54,6 +54,8 @@ The scan skips what `.gitignore` ignores, the `node_modules`, `vendor`, `build`,
 
 With `--json`, `scan` prints the references for scripts and CI; `schema/scan-output.schema.json` in the package describes that output. Each reference has a `kind`, `direct` or `indirect`, and a direct reference resolved from a constant carries the constant as `argument`.
 
+Each direct and indirect reference in the JSON also carries a `snippet`: its line and the 2 lines before and after it, without line endings, with any line longer than 250 characters cut to its first 250. `--context-lines <number>` includes from 0 to 5 lines on each side, and `--no-snippets` leaves every snippet out; giving both exits with 2. Dynamic references have no snippet, and the text output shows none.
+
 ## Upload the scan to ConfigDirector
 
 From the repository root, on the default branch:
@@ -68,6 +70,8 @@ The repository is named after the path of its git remote `origin`, without the h
 
 The upload holds the references and dynamic references `scan --json` prints, whatever `ignoreKeys` lists, except a reference to a key that cannot be a config key, such as one shorter than 4 characters, which is left out and counted. The output is the scan's, then a line naming the repository, the commit, the project, how many references were sent and how many were left out. A scan that finds no source file exits with 2 and uploads nothing, so a wrong path or `include` never empties the repository's references; a scan that reads files and finds no reference uploads an empty set. With `--json`, it prints the Admin API's response as received.
 
+Each direct and indirect reference is sent with its snippet, so the dashboard can show the code around it; `--no-snippets` sends no code, and `--context-lines` sets how many lines are sent. When the project's Code snippets setting is off, `scan --upload` sends no snippets and ends with `Code snippets were not sent: this project does not store them.`
+
 A project holds at most 50 scanned repositories, and one upload holds at most 10,000 references, dynamic references included; going over either exits with 2. `scan --upload` needs `projects:read`, `configs:read` and `code-references:update`. Uploads do not appear in the audit log.
 
 ## List and remove scanned repositories

package/dist/configdirector.mjs

@@ -12,7 +12,7 @@ import { promisify } from "node:util";
 import { randomUUID } from "node:crypto";
 import { text } from "node:stream/consumers";
 //#region package.json
-var version = "0.8.0-beta.1";
+var version = "0.9.0-beta.1";
 //#endregion
 //#region src/CliError.ts
 var CliError = class extends Error {
@@ -677,7 +677,8 @@ const ConfigEvaluationSchema = v.object({
 const ProjectSchema = v.object({
 	id: v.string(),
 	name: v.string(),
-	slug: v.string()
+	slug: v.string(),
+	storeCodeSnippets: v.optional(v.boolean(), true)
 });
 const configFields = {
 	key: v.string(),
@@ -1530,6 +1531,25 @@ const languageOfExtension = {
 	".go": "go"
 };
 const isSourceExtension = (extension) => Object.hasOwn(languageOfExtension, extension);
+const snippetLanguageOfExtension = {
+	".js": "javascript",
+	".jsx": "jsx",
+	".mjs": "javascript",
+	".cjs": "javascript",
+	".ts": "typescript",
+	".tsx": "tsx",
+	".mts": "typescript",
+	".cts": "typescript",
+	".vue": "vue",
+	".svelte": "svelte",
+	".dart": "dart",
+	".swift": "swift",
+	".kt": "kotlin",
+	".java": "java",
+	".py": "python",
+	".cs": "csharp",
+	".go": "go"
+};
 const languageSyntax = {
 	javascript: {
 		lineComment: "//",
@@ -3587,6 +3607,43 @@ const sdkCallMatches = (code, callShapes) => {
 	return matches;
 };
 //#endregion
+//#region src/scan/snippets.ts
+const MAXIMUM_LINE_LENGTH = 250;
+const linesOf = (contents) => {
+	const lines = contents.split("\n");
+	return lines.at(-1) === "" ? lines.slice(0, -1) : lines;
+};
+const withoutCarriageReturn = (line) => line.endsWith("\r") ? line.slice(0, -1) : line;
+const snippetOfLines = (fileLines, line, contextLines, language) => {
+	const firstLine = Math.max(1, line - contextLines);
+	const lastLine = Math.min(fileLines.length, line + contextLines);
+	const lines = [];
+	const truncatedLines = [];
+	for (let lineNumber = firstLine; lineNumber <= lastLine; lineNumber += 1) {
+		const text = withoutCarriageReturn(fileLines[lineNumber - 1]);
+		if (text.length > MAXIMUM_LINE_LENGTH) truncatedLines.push(lineNumber);
+		lines.push(text.slice(0, MAXIMUM_LINE_LENGTH));
+	}
+	return {
+		firstLine,
+		lines,
+		language,
+		truncatedLines
+	};
+};
+const snippetCutterFor = (file, cut) => {
+	switch (cut.kind) {
+		case "no-snippets": return () => void 0;
+		case "around-each-reference": {
+			let fileLines;
+			return (line) => {
+				fileLines ??= linesOf(file.contents);
+				return snippetOfLines(fileLines, line, cut.contextLines, snippetLanguageOfExtension[file.extension]);
+			};
+		}
+	}
+};
+//#endregion
 //#region src/scan/test-files.ts
 const TEST_DIRECTORY_NAMES = new Set([
 	"test",
@@ -3644,12 +3701,13 @@ const matchesIn = (file, code, callShapes, projectKeys, constantNameOfToken) =>
 };
 const matchOutcomes = (matches, constantIndex) => {
 	const constantsReadByCalls = new Set(matches.flatMap((match) => match.kind === "named" && constantIndex.keyOf(match.name) !== void 0 ? [match.name] : []));
-	return matches.map(({ file, ...match }) => {
+	return matches.map(({ file, snippet, ...match }) => {
 		switch (match.kind) {
 			case "direct": return {
 				file,
 				kind: "direct",
-				reference: match.reference
+				reference: match.reference,
+				snippet
 			};
 			case "dynamic": return {
 				file,
@@ -3668,7 +3726,8 @@ const matchOutcomes = (matches, constantIndex) => {
 					reference: {
 						...match.reference,
 						key
-					}
+					},
+					snippet
 				};
 			}
 			case "indirect": return match.constantName !== void 0 && constantsReadByCalls.has(match.constantName) ? {
@@ -3677,7 +3736,8 @@ const matchOutcomes = (matches, constantIndex) => {
 			} : {
 				file,
 				kind: "indirect",
-				reference: match.reference
+				reference: match.reference,
+				snippet
 			};
 		}
 	});
@@ -3762,7 +3822,7 @@ const sdkFamiliesUsedIn = (highestDirectory) => {
 		return usedFamilies;
 	};
 };
-const scanCodeReferences = async (scope, projectKeys) => {
+const scanCodeReferences = async (scope, projectKeys, snippetCut) => {
 	const scan = {
 		filesScanned: 0,
 		references: [],
@@ -3781,9 +3841,11 @@ const scanCodeReferences = async (scope, projectKeys) => {
 		const constantAssignments = constantAssignmentsIn(code);
 		for (const assignment of constantAssignments) constantIndex.add(assignment);
 		const constantNameOfToken = new Map(constantAssignments.map((assignment) => [assignment.tokenIndex, assignment.name]));
+		const snippetAround = snippetCutterFor(file, snippetCut);
 		matches.push(...matchesIn(file, code, callShapes, projectKeys, constantNameOfToken).map((match) => ({
 			...match,
-			file: file.displayPath
+			file: file.displayPath,
+			snippet: snippetAround(match.reference.line)
 		})));
 	}
 	for (const outcome of matchOutcomes(matches, constantIndex)) switch (outcome.kind) {
@@ -3791,14 +3853,16 @@ const scanCodeReferences = async (scope, projectKeys) => {
 			scan.references.push({
 				...outcome.reference,
 				kind: "direct",
-				file: outcome.file
+				file: outcome.file,
+				snippet: outcome.snippet
 			});
 			break;
 		case "indirect":
 			scan.references.push({
 				...outcome.reference,
 				kind: "indirect",
-				file: outcome.file
+				file: outcome.file,
+				snippet: outcome.snippet
 			});
 			break;
 		case "dynamic":
@@ -3813,7 +3877,7 @@ const scanCodeReferences = async (scope, projectKeys) => {
 };
 //#endregion
 //#region src/project-scan.ts
-const scanProject = async (context, root) => {
+const connectToScannableProject = async (context) => {
 	const { workingDirectory } = context.invocation;
 	const settings = await readProjectSettings(workingDirectory);
 	const projectSlug = requireLinkedProjectSlug(context, settings);
@@ -3824,18 +3888,17 @@ const scanProject = async (context, root) => {
 	const project = await findProjectBySlug(client, projectSlug);
 	const configs = (await client.listConfigs(project.id, { form: "every-config" })).map((listedConfig) => listedConfig.config);
 	const projectKeys = new Set(configs.flatMap((config) => [config.key, ...config.deprecatedKeys.map((deprecatedKey) => deprecatedKey.key)]));
-	const codeReferenceScan = await scanCodeReferences({
-		root,
-		workingDirectory,
-		include: settings?.include ?? "everyFile",
-		exclude: settings?.exclude ?? []
-	}, projectKeys);
 	return {
 		client,
 		project,
 		configs,
 		ignoredKeys: new Set(settings?.ignoreKeys ?? []),
-		codeReferenceScan
+		codeReferencesIn: (root, snippetCut) => scanCodeReferences({
+			root,
+			workingDirectory,
+			include: settings?.include ?? "everyFile",
+			exclude: settings?.exclude ?? []
+		}, projectKeys, snippetCut)
 	};
 };
 //#endregion
@@ -3945,14 +4008,16 @@ const referenceJson = (reference) => {
 			...reference.argument === void 0 ? {} : { argument: reference.argument },
 			...reference.inCodeDefault === void 0 ? {} : { default: reference.inCodeDefault },
 			...reference.getterType === void 0 ? {} : { getterType: reference.getterType },
-			test: reference.test
+			test: reference.test,
+			...reference.snippet === void 0 ? {} : { snippet: reference.snippet }
 		};
 		case "indirect": return {
 			key: reference.key,
 			file: reference.file,
 			line: reference.line,
 			kind: reference.kind,
-			test: reference.test
+			test: reference.test,
+			...reference.snippet === void 0 ? {} : { snippet: reference.snippet }
 		};
 	}
 };
@@ -4010,9 +4075,24 @@ const scanText = (scan, scannedLocation) => {
 };
 const shortCommitText = (commit) => commit === null ? "" : ` at ${shortCommit(commit)}`;
 const uploadLine = (projectSlug, repository, leftOutCount) => `Uploaded the scan of ${repository.name}${shortCommitText(repository.commit)} to ${projectSlug}: ${repository.referenceCount} ${plural(repository.referenceCount, "reference", "references")} and ${repository.dynamicReferenceCount} ${plural(repository.dynamicReferenceCount, "dynamic reference", "dynamic references")}, with ${leftOutCount} left out for a key that cannot be a config key.`;
-const uploadScan = async (context, root, repositoryOption) => {
+const snippetsSentTo = (project, requestedSnippetCut) => project.storeCodeSnippets ? {
+	kind: "as-requested",
+	snippetCut: requestedSnippetCut
+} : {
+	kind: "project-stores-none",
+	snippetCut: { kind: "no-snippets" }
+};
+const snippetsSentText = (snippetsSent) => {
+	switch (snippetsSent.kind) {
+		case "as-requested": return "";
+		case "project-stores-none": return "Code snippets were not sent: this project does not store them.\n";
+	}
+};
+const uploadScan = async (context, root, repositoryOption, requestedSnippetCut) => {
 	const repository = repositoryIdentityOf(await readGitCheckout(scanRootDirectory(root), context.invocation.environmentVariables), repositoryOption, root.description);
-	const { client, project, codeReferenceScan } = await scanProject(context, root);
+	const { client, project, codeReferencesIn } = await connectToScannableProject(context);
+	const snippetsSent = snippetsSentTo(project, requestedSnippetCut);
+	const codeReferenceScan = await codeReferencesIn(root, snippetsSent.snippetCut);
 	if (codeReferenceScan.filesScanned === 0) throw new CliError(`No source files to scan in ${root.description}, so nothing was uploaded and ${project.slug} keeps its code references for ${repository.name}. Check the path given to scan, and include and exclude in configdirector.json.`);
 	const configKeyReferences = codeReferenceScan.references.filter((reference) => fitsKeyGrammar(reference.key));
 	const leftOutCount = codeReferenceScan.references.length - configKeyReferences.length;
@@ -4026,14 +4106,26 @@ const uploadScan = async (context, root, repositoryOption) => {
 	});
 	return {
 		json: responseBody,
-		text: `${scanText(codeReferenceScan, root.description)}\n${uploadLine(project.slug, scannedRepository, leftOutCount)}\n`,
+		text: `${scanText(codeReferenceScan, root.description)}\n${uploadLine(project.slug, scannedRepository, leftOutCount)}\n` + snippetsSentText(snippetsSent),
 		exitCode: ExitCode.success
 	};
 };
+const contextLinesOf = (text) => {
+	if (text === void 0) return 2;
+	const contextLines = /^\d+$/.test(text) ? Number(text) : void 0;
+	if (contextLines === void 0 || contextLines > 5) throw new CliError(`--context-lines takes a whole number from 0 to 5, not ${text}.`);
+	return contextLines;
+};
+const snippetCutOf = (options) => options.snippets ? {
+	kind: "around-each-reference",
+	contextLines: contextLinesOf(options.contextLines)
+} : { kind: "no-snippets" };
 const scan = async (context, [path], options) => {
+	const snippetCut = snippetCutOf(options);
 	const root = await scanRootAt(context.invocation.workingDirectory, path);
-	if (options.upload) return uploadScan(context, root, options.repository);
-	const { project, codeReferenceScan } = await scanProject(context, root);
+	if (options.upload) return uploadScan(context, root, options.repository, snippetCut);
+	const { project, codeReferencesIn } = await connectToScannableProject(context);
+	const codeReferenceScan = await codeReferencesIn(root, snippetCut);
 	return {
 		json: scanJson(project.slug, codeReferenceScan),
 		text: scanText(codeReferenceScan, root.description),
@@ -4370,7 +4462,8 @@ const validateText = (projectSlug, scan, scannedLocation, check) => {
 };
 const validate = async (context, [path]) => {
 	const root = await scanRootAt(context.invocation.workingDirectory, path);
-	const { project, configs, ignoredKeys, codeReferenceScan } = await scanProject(context, root);
+	const { project, configs, ignoredKeys, codeReferencesIn } = await connectToScannableProject(context);
+	const codeReferenceScan = await codeReferencesIn(root, { kind: "no-snippets" });
 	const check = checkCodeReferences(codeReferenceScan.references, configs, ignoredKeys);
 	return {
 		json: {
@@ -4422,7 +4515,7 @@ const run = async (invocation) => {
 	});
 	program.command("login").description("save an API token for later runs, after checking it can list projects").action(commandAction(login));
 	program.command("init").description("write configdirector.json for a project in the current directory").action(commandAction(init));
-	program.command("scan").argument("[path]", "directory or file to scan (default: the current directory)").description("list where the code reads config keys through a ConfigDirector SDK").option("--upload", "send the code references to the project, replacing those it holds for this repository").option("--repository <name>", "the repository name to upload under (default: the path of the git remote origin, such as ConfigDirector/cli)").action(commandAction(scan));
+	program.command("scan").argument("[path]", "directory or file to scan (default: the current directory)").description("list where the code reads config keys through a ConfigDirector SDK").option("--upload", "send the code references to the project, replacing those it holds for this repository").option("--repository <name>", "the repository name to upload under (default: the path of the git remote origin, such as ConfigDirector/cli)").addOption(new Option("--context-lines <number>", `how many lines of code to include before and after each reference, from 0 to 5 (default: 2)`).conflicts("snippets")).option("--no-snippets", "leave out the lines of code around each reference").action(commandAction(scan));
 	program.command("validate").argument("[path]", "directory or file to check (default: the current directory)").description("check every config key the code reads against the project's configs, exiting 1 when one is wrong").action(commandAction(validate));
 	program.command("evaluate").argument("<key>", "the config's key").description("show the value a context gets for a config in an environment, and why").requiredOption("--environment <slug>", "slug of the environment whose targeting rules to evaluate (required)").option("--context-kind <kind>", "context kind of the context to evaluate for (default: user)").option("--context-id <identifier>", "identifier of the context").option("--context-name <name>", "name of the context").option("--context-trait <name=value>", "a trait of the context, as a string, or name:=<json> for a number, boolean, array or object; repeatable", repeatedOption).option("--context-json <json>", "the whole context as a JSON object, or @<file> to read it from a file").option("--saved-context <kind:identifier>", "a context ConfigDirector saved from SDK evaluations in the environment, such as user:123").addHelpText("after", "\nGive the context with the --context-* options, with --context-json, or with --saved-context. Without any of them, the config is evaluated for an empty context, as an SDK given none would.").action(commandAction(evaluate));
 	program.command("projects").description("list the projects of the API token's organization").command("list").description("list the organization's projects, whatever project is selected").action(commandAction(listProjects));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@configdirector/cli",
-  "version": "0.8.0-beta.1",
+  "version": "0.9.0-beta.1",
   "description": "Command line tool for ConfigDirector, the managed configuration and feature flag service.",
   "license": "MIT",
   "author": "ConfigDirector",

package/schema/scan-output.schema.json

@@ -149,6 +149,9 @@
         },
         "test": {
           "$ref": "#/$defs/test"
+        },
+        "snippet": {
+          "$ref": "#/$defs/snippet"
         }
       }
     },
@@ -174,6 +177,58 @@
         "test": {
           "description": "Whether the file is in a test directory or has a test name.",
           "type": "boolean"
+        },
+        "snippet": {
+          "$ref": "#/$defs/snippet"
+        }
+      }
+    },
+    "snippet": {
+      "description": "The reference line and the lines around it, as many before and after it as --context-lines asks for and the file holds. Absent with --no-snippets, and in `configdirector validate --json` output.",
+      "type": "object",
+      "required": ["firstLine", "lines", "language", "truncatedLines"],
+      "additionalProperties": false,
+      "properties": {
+        "firstLine": {
+          "description": "The number of the snippet's first line in the file, starting at 1.",
+          "type": "integer",
+          "minimum": 1
+        },
+        "lines": {
+          "description": "The lines, in order, without their line endings. A line longer than 250 characters is cut to its first 250.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 11,
+          "items": {
+            "type": "string",
+            "maxLength": 250
+          }
+        },
+        "language": {
+          "description": "The language to highlight the lines as, from the file's extension.",
+          "enum": [
+            "typescript",
+            "tsx",
+            "javascript",
+            "jsx",
+            "vue",
+            "svelte",
+            "dart",
+            "swift",
+            "kotlin",
+            "java",
+            "python",
+            "csharp",
+            "go"
+          ]
+        },
+        "truncatedLines": {
+          "description": "The numbers of the lines that were cut to 250 characters, empty when none was.",
+          "type": "array",
+          "items": {
+            "type": "integer",
+            "minimum": 1
+          }
         }
       }
     },