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

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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
+
+- `configdirector repositories list` lists the repositories whose scan was uploaded to the project, one per line, with the commit, when it was scanned in UTC, and how many references and dynamic references it holds, and ends with how many scanned repositories the project has out of the 50 it can hold, as in `web-app has 2 of the 50 scanned repositories a project can hold.` A repository uploaded without a commit shows `no commit`. With `--json`, it prints the Admin API's response as received. It needs `projects:read` and `code-references:read`.
+- `configdirector repositories remove <name>` removes a scanned repository and all its references from the project, so a repository that was renamed or retired stops counting toward the 50, and the dashboard stops using its references to show where each config is read and which configs no repository reads. It asks for no confirmation and prints `Removed acme/storefront and its code references from web-app.`; `--json` prints `{ "removedRepository": "acme/storefront" }` with the name as given. When no scanned repository in the project has the name, it exits with 2 and lists the names the project has. It needs `projects:read` and `code-references:update`, and `code-references:read` to list the names. Removals do not appear in the audit log.
+
+## [0.7.0-beta.1] - 2026-10-17
+
+### Added
+
+- `configdirector scan --upload` sends the scan to the project, so the dashboard can show where each config is read and which configs no repository reads. Each upload replaces all the references the project held for the repository. The CLI does not check which branch is checked out, so run it on pushes to the default branch, and keep `validate` for pull requests.
+- The repository is named after the path of its git remote `origin`, without the host and `.git`, so `https://github.com/acme/shop.git`, `git@github.com:acme/shop.git` and `ssh://git@github.com/acme/shop.git` all upload to `acme/shop`. The upload also sends the remote's URL and the commit checked out, both read by running `git`; the user name and password of an `https` remote, such as the job token GitLab CI puts there, are removed first. `--repository <name>` names the repository yourself. Without it, `scan --upload` exits with 2 when `git` is not installed, when the directory is not in a git repository, or when that repository has no `origin` remote; with it, each of those cases uploads with no remote URL and no commit. A repository with no commit yet uploads with no commit.
+- 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, which is left out and counted. The output is the scan's, then a line such as `Uploaded the scan of acme/shop at 4d40f50 to web-app: 12 references and 1 dynamic reference, with 0 left out for a key that cannot be a config key.` With `--json`, it prints the Admin API's response as received.
+- 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. When the project already holds its maximum of scanned repositories, `scan --upload` exits with 2 and names `configdirector repositories remove`. It needs `projects:read`, `configs:read` and `code-references:update`.
+
+## [0.6.0-beta.1] - 2026-10-17
+
+### Added
+
+- `configdirector configs archive <key>` archives a config: it is removed from the project and from what SDKs receive, so applications get their in-code default value for it. It can be restored from the dashboard for 30 days, and after that it is deleted for good. The key can be the config's current key or an old one.
+- `configs archive` asks for no confirmation and does not check whether the code still reads the key, so run `configdirector scan` first. It prints `Archived new-checkout in web-app. It can be restored from the dashboard for 30 days.`, and `--json` prints `{ "archivedConfigKey": "new-checkout" }` with the key as given, as the MCP server's `archive_config` tool does. It exits with 2 when no config in the project has the key, which includes a config already archived. It needs `projects:read` and `configs:archive`. The change shows in the audit log with the source CLI.
+
 ## [0.5.0-beta.1] - 2026-10-17
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # ConfigDirector CLI
 
-`configdirector` is the command line tool for [ConfigDirector](https://www.configdirector.com), the managed configuration and feature flag service. It is in beta: commands and output may change before 1.0. This release signs in, links a repository to a project, lists where the repository's code reads config keys, checks those keys against the project's configs, shows the value a context gets for a config and why, reads a project's environments, configs, targeting rules and segments, creates configs, and replaces a config's targeting rules in an environment.
+`configdirector` is the command line tool for [ConfigDirector](https://www.configdirector.com), the managed configuration and feature flag service. It is in beta: commands and output may change before 1.0. This release signs in, links a repository to a project, lists where the repository's code reads config keys, checks those keys against the project's configs, shows the value a context gets for a config and why, reads a project's environments, configs, targeting rules and segments, creates configs, replaces a config's targeting rules in an environment, archives configs, uploads the repository's code references to the project, and lists and removes the project's scanned repositories.
 
 The [CLI page of the ConfigDirector docs](https://docs.configdirector.com/integrations/cli) covers the API token, CI setup for GitHub Actions and GitLab, and what each problem `validate` reports means for your build.
 
@@ -54,6 +54,51 @@ 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:
+
+```bash
+configdirector scan --upload
+```
+
+`--upload` sends the scan to the project, so the dashboard can show where each config is read and which configs no repository reads. Each upload replaces all the references the project held for the repository. The CLI does not check which branch is checked out, so run it on pushes to the default branch, and keep `validate` for pull requests.
+
+The repository is named after the path of its git remote `origin`, without the host and `.git`: `https://github.com/acme/shop.git`, `git@github.com:acme/shop.git` and `ssh://git@github.com/acme/shop.git` all upload to `acme/shop`, and a GitLab subgroup keeps its whole path, such as `group/subgroup/app`. The upload also sends the remote's URL, without the user name and password of an `https` remote, such as the job token GitLab CI puts there, and the commit checked out, both read by running `git`. `--repository <name>` names the repository yourself. Without it, `scan --upload` exits with 2 when `git` is not installed, when the directory is not in a git repository, or when that repository has no `origin` remote; with it, each of those cases uploads with no remote URL and no commit. A repository with no commit yet uploads with no commit.
+
+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
+
+```bash
+configdirector repositories list
+```
+
+`repositories list` lists the repositories whose scan was uploaded to the project, one per line, with the commit, when it was scanned in UTC, and how many references and dynamic references it holds, and ends with how many scanned repositories the project has out of the 50 it can hold:
+
+```txt
+ConfigDirector/cli   4d40f50   2026-10-17 10:00 UTC   12 references   1 dynamic reference
+acme/storefront      9f3e2a1   2026-10-16 09:12 UTC   1 reference     0 dynamic references
+
+web-app has 2 of the 50 scanned repositories a project can hold.
+```
+
+A repository uploaded without a commit shows `no commit`. With `--json`, it prints the Admin API's response as received, which also holds each repository's remote URL and how many files its scan read. `repositories list` needs `projects:read` and `code-references:read`.
+
+```bash
+configdirector repositories remove acme/storefront
+```
+
+Nothing removes a scanned repository on its own: a repository that is renamed or retired keeps its last upload, keeps counting toward the 50, and the dashboard keeps using its references to show where each config is read and which configs no repository reads. `repositories remove <name>` removes the repository and all its references from the project, with no confirmation, and prints `Removed acme/storefront and its code references from web-app.` To rename a repository, remove the old name and upload under the new one; a removed repository that uploads again is added back. When no scanned repository in the project has the name, it exits with 2 and lists the names the project has. With `--json`, it prints `{ "removedRepository": "acme/storefront" }`, with the name as given.
+
+`repositories remove` needs `projects:read` and `code-references:update`, and `code-references:read` to list the names when none matches. Removals do not appear in the audit log.
+
 ## Check the keys the code reads
 
 From the repository root, or as a CI step:
@@ -217,6 +262,22 @@ configdirector targeting-rules set new-checkout --environment production --rules
 
 `targeting-rules set` needs `projects:read`, `environments:read` and `config-targeting-rules:update`. `targeting-rules reference` needs only a valid token and no project.
 
+## Archive a config
+
+```bash
+configdirector configs archive new-checkout
+```
+
+`configs archive` archives a config: it is removed from the project and from what SDKs receive, so applications get their in-code default value for it. It can be restored from the dashboard for 30 days, and after that it is deleted for good:
+
+```txt
+Archived new-checkout in web-app. It can be restored from the dashboard for 30 days.
+```
+
+It asks for no confirmation and does not check whether the code still reads the key, so run `configdirector scan` first. A renamed config can be archived by an old key. When no config in the project has the key, which includes a config already archived, it exits with 2. With `--json`, it prints `{ "archivedConfigKey": "new-checkout" }`, with the key as given.
+
+`configs archive` needs `projects:read` and `configs:archive`. The change shows in the audit log with the source CLI.
+
 ## Options
 
 | Option             | Environment variable      | Meaning                                                                                                       |
@@ -226,7 +287,7 @@ configdirector targeting-rules set new-checkout --environment production --rules
 | `--project <slug>` | `CONFIGDIRECTOR_PROJECT`  | Project slug. Without either, every command that reads a project uses the `project` in `configdirector.json`. |
 | `--json`           |                           | Print JSON on stdout. Errors always go to stderr.                                                             |
 
-The command exits with 0 when it succeeds, 1 when `validate` found a problem or `configs create` found a config that already has the key, and 2 when it could not run: a usage mistake, a rejected token, a suspended service, an unreachable API, or something the command names that does not exist, such as a config key, an environment, a saved context, a segment key or a tag. A CI job can therefore tell a wrong config key from an outage.
+The command exits with 0 when it succeeds, 1 when `validate` found a problem or `configs create` found a config that already has the key, and 2 when it could not run: a usage mistake, a rejected token, a suspended service, an unreachable API, or something the command names that does not exist, such as a config key, an environment, a saved context, a segment key, a tag or a scanned repository. A CI job can therefore tell a wrong config key from an outage.
 
 ## License
 

package/dist/configdirector.mjs

@@ -7,10 +7,12 @@ import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep }
 import { createInterface } from "node:readline";
 import ignore from "ignore";
 import picomatch from "picomatch";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { randomUUID } from "node:crypto";
 import { text } from "node:stream/consumers";
 //#region package.json
-var version = "0.5.0-beta.1";
+var version = "0.9.0-beta.1";
 //#endregion
 //#region src/CliError.ts
 var CliError = class extends Error {
@@ -40,6 +42,7 @@ const ApiValidationErrorBodySchema = v.object({ errors: v.array(v.object({
 	message: v.string()
 })) });
 const ServiceSuspendedBodySchema = v.object({ code: v.literal("SERVICE_SUSPENDED") });
+const RepositoryLimitReachedBodySchema = v.object({ code: v.literal("REPOSITORY_LIMIT_REACHED") });
 const EvaluationNotFoundBodySchema = v.object({
 	error: v.string(),
 	code: v.picklist([
@@ -75,6 +78,11 @@ var EvaluationNotFoundError = class extends CliError {
 		this.code = code;
 	}
 };
+var RepositoryLimitReachedError = class extends CliError {
+	constructor() {
+		super("The project already holds its maximum of scanned repositories, so the Admin API refused the upload (REPOSITORY_LIMIT_REACHED). Remove a repository it no longer needs with `configdirector repositories remove <name>`, then upload again.");
+	}
+};
 var ServiceSuspendedError = class extends CliError {
 	constructor(retryAfterSeconds) {
 		super(`Your organization's service is suspended, so ConfigDirector refuses Admin API requests. The dashboard's billing page shows why and how to reinstate it. Retry after ${retryAfterSeconds} seconds.`);
@@ -556,6 +564,19 @@ const CreatedConfigSchema = v.object({
 	server: v.boolean()
 });
 //#endregion
+//#region src/admin-api/scanned-repositories.ts
+const scannedRepositoryFields = {
+	name: v.string(),
+	commit: v.pipe(v.string(), v.transform((commit) => commit === "" ? null : commit)),
+	referenceCount: v.number(),
+	dynamicReferenceCount: v.number()
+};
+const ScannedRepositorySchema = v.object(scannedRepositoryFields);
+const ListedScannedRepositorySchema = v.object({
+	...scannedRepositoryFields,
+	scannedAt: v.pipe(v.string(), v.isoTimestamp())
+});
+//#endregion
 //#region src/admin-api/segments.ts
 const SegmentSchema = v.object({
 	id: v.string(),
@@ -656,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(),
@@ -713,6 +735,7 @@ const describeStatus = (response) => `HTTP ${response.status}`;
 const failureFor = (url, response, body) => {
 	switch (response.status) {
 		case 400: {
+			if (v.is(RepositoryLimitReachedBodySchema, body)) return new RepositoryLimitReachedError();
 			const validationError = v.safeParse(ApiValidationErrorBodySchema, body);
 			return validationError.success ? new ApiValidationError(validationError.output.errors) : new UnexpectedApiResponseError(url, describeStatus(response));
 		}
@@ -799,6 +822,21 @@ var AdminApiClient = class {
 			body: request
 		}) === void 0 ? "not-found" : "replaced";
 	}
+	uploadRepositoryScan(projectId, repositoryName, upload) {
+		return this.requestJson(`/v1/projects/${encodeURIComponent(projectId)}/repositories/${encodeURIComponent(repositoryName)}`, ScannedRepositorySchema, {
+			method: "PUT",
+			body: upload
+		});
+	}
+	listScannedRepositories(projectId) {
+		return this.get(`/v1/projects/${encodeURIComponent(projectId)}/repositories`, v.array(ListedScannedRepositorySchema));
+	}
+	async removeScannedRepository(projectId, repositoryName) {
+		return await this.requestIfFound(`/v1/projects/${encodeURIComponent(projectId)}/repositories/${encodeURIComponent(repositoryName)}`, v.unknown(), { method: "DELETE" }) === void 0 ? "not-found" : "removed";
+	}
+	async archiveConfig(projectId, configKey) {
+		return await this.requestIfFound(`/v1/projects/${encodeURIComponent(projectId)}/configs/${encodeURIComponent(configKey)}`, v.unknown(), { method: "DELETE" }) === void 0 ? "not-found" : "archived";
+	}
 	get(path, schema) {
 		return this.requestJson(path, schema, { method: "GET" });
 	}
@@ -829,13 +867,16 @@ var AdminApiClient = class {
 			"X-SourceClient": "cli"
 		};
 		try {
-			return await fetch(url, request.method === "GET" ? { headers } : {
+			return await fetch(url, "body" in request ? {
 				method: request.method,
 				headers: {
 					...headers,
 					"Content-Type": "application/json"
 				},
 				body: JSON.stringify(request.body)
+			} : {
+				method: request.method,
+				headers
 			});
 		} catch (error) {
 			throw new ApiUnreachableError(this.connection.baseUrl, error);
@@ -934,6 +975,12 @@ const connectToLinkedProject = async (context) => {
 	};
 };
 //#endregion
+//#region src/utc-minute.ts
+const utcMinute = (time) => {
+	const isoTime = new Date(time).toISOString();
+	return `${isoTime.slice(0, 10)} ${isoTime.slice(11, 16)} UTC`;
+};
+//#endregion
 //#region src/commands/configs.ts
 const LIFECYCLE_STATES = [
 	"new",
@@ -1047,11 +1094,16 @@ const createConfig = async (context, _commandArguments, options) => {
 		tagIds: await tagIdsNamed(client, project, options.tag ?? [])
 	}));
 };
-const sdkDescription = (evaluation) => [evaluation.sdkName ?? "unknown SDK", ...evaluation.sdkVersion === null ? [] : [evaluation.sdkVersion]].join(" ");
-const utcMinute = (time) => {
-	const isoTime = new Date(time).toISOString();
-	return `${isoTime.slice(0, 10)} ${isoTime.slice(11, 16)} UTC`;
+const archiveConfig = async (context, [configKey]) => {
+	const { client, project } = await connectToLinkedProject(context);
+	if (await client.archiveConfig(project.id, configKey) === "not-found") throw new CliError(`No config in ${project.slug} has the key "${configKey}".`);
+	return {
+		json: { archivedConfigKey: configKey },
+		text: [`Archived ${configKey} in ${project.slug}. It can be restored from the dashboard for 30 days.`, ""].join("\n"),
+		exitCode: ExitCode.success
+	};
 };
+const sdkDescription = (evaluation) => [evaluation.sdkName ?? "unknown SDK", ...evaluation.sdkVersion === null ? [] : [evaluation.sdkVersion]].join(" ");
 const activityLines = (configKey, activity) => activity.latestEvaluations.length === 0 ? [`No SDK evaluations of ${configKey} found.`] : alignedColumns(activity.latestEvaluations.map((evaluation) => [
 	evaluation.environment.slug,
 	evaluation.source,
@@ -1415,6 +1467,49 @@ const listProjects = async (context) => {
 //#region src/plural.ts
 const plural = (count, singular, pluralForm) => count === 1 ? singular : pluralForm;
 //#endregion
+//#region src/scanned-repository/short-commit.ts
+const SHORT_COMMIT_LENGTH = 7;
+const shortCommit = (commit) => commit.slice(0, SHORT_COMMIT_LENGTH);
+//#endregion
+//#region src/commands/repositories.ts
+const MAX_SCANNED_REPOSITORIES_PER_PROJECT = 50;
+const commitDescription = (commit) => commit === null ? "no commit" : shortCommit(commit);
+const scannedRepositoryColumnsOf = (repository) => [
+	repository.name,
+	commitDescription(repository.commit),
+	utcMinute(repository.scannedAt),
+	`${repository.referenceCount} ${plural(repository.referenceCount, "reference", "references")}`,
+	`${repository.dynamicReferenceCount} ${plural(repository.dynamicReferenceCount, "dynamic reference", "dynamic references")}`
+];
+const scannedRepositoryLines = (projectSlug, repositories) => repositories.length === 0 ? [`No scanned repositories found in ${projectSlug}. Run configdirector scan --upload in a repository to upload its code references.`] : [
+	...alignedColumns(repositories.map(scannedRepositoryColumnsOf)),
+	"",
+	`${projectSlug} has ${repositories.length} of the ${MAX_SCANNED_REPOSITORIES_PER_PROJECT} scanned repositories a project can hold.`
+];
+const listScannedRepositories = async (context) => {
+	const { client, project } = await connectToLinkedProject(context);
+	const { parsedBody: repositories, responseBody } = await client.listScannedRepositories(project.id);
+	return {
+		json: responseBody,
+		text: [...scannedRepositoryLines(project.slug, repositories), ""].join("\n"),
+		exitCode: ExitCode.success
+	};
+};
+const scannedRepositoryNamesSentence = (repositories) => repositories.length === 0 ? "The project has no scanned repositories." : `Its scanned repositories are ${repositories.map((repository) => repository.name).join(", ")}.`;
+const scannedRepositoryNotFoundError = async (client, project, repositoryName) => {
+	const repositories = await ifPermitted(client.listScannedRepositories(project.id));
+	return new CliError([`No scanned repository in ${project.slug} has the name "${repositoryName}".`, ...repositories === void 0 ? [] : [scannedRepositoryNamesSentence(repositories.parsedBody)]].join(" "));
+};
+const removeScannedRepository = async (context, [repositoryName]) => {
+	const { client, project } = await connectToLinkedProject(context);
+	if (await client.removeScannedRepository(project.id, repositoryName) === "not-found") throw await scannedRepositoryNotFoundError(client, project, repositoryName);
+	return {
+		json: { removedRepository: repositoryName },
+		text: [`Removed ${repositoryName} and its code references from ${project.slug}.`, ""].join("\n"),
+		exitCode: ExitCode.success
+	};
+};
+//#endregion
 //#region src/scan/source-languages.ts
 const languageOfExtension = {
 	".js": "javascript",
@@ -1436,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: "//",
@@ -1886,6 +2000,7 @@ const scanRootAt = async (workingDirectory, path) => {
 		description: path ?? "the current directory"
 	};
 };
+const scanRootDirectory = (root) => root.isDirectory ? root.path : dirname(root.path);
 const gitignoreRulesIn = async (directory) => {
 	const contents = await readFileIfPresent(join(directory, ".gitignore"));
 	return contents === void 0 ? [] : [{
@@ -3492,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",
@@ -3549,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,
@@ -3573,7 +3726,8 @@ const matchOutcomes = (matches, constantIndex) => {
 					reference: {
 						...match.reference,
 						key
-					}
+					},
+					snippet
 				};
 			}
 			case "indirect": return match.constantName !== void 0 && constantsReadByCalls.has(match.constantName) ? {
@@ -3582,7 +3736,8 @@ const matchOutcomes = (matches, constantIndex) => {
 			} : {
 				file,
 				kind: "indirect",
-				reference: match.reference
+				reference: match.reference,
+				snippet
 			};
 		}
 	});
@@ -3667,7 +3822,7 @@ const sdkFamiliesUsedIn = (highestDirectory) => {
 		return usedFamilies;
 	};
 };
-const scanCodeReferences = async (scope, projectKeys) => {
+const scanCodeReferences = async (scope, projectKeys, snippetCut) => {
 	const scan = {
 		filesScanned: 0,
 		references: [],
@@ -3686,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) {
@@ -3696,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":
@@ -3718,11 +3877,10 @@ const scanCodeReferences = async (scope, projectKeys) => {
 };
 //#endregion
 //#region src/project-scan.ts
-const scanProject = async (context, path) => {
+const connectToScannableProject = async (context) => {
 	const { workingDirectory } = context.invocation;
 	const settings = await readProjectSettings(workingDirectory);
 	const projectSlug = requireLinkedProjectSlug(context, settings);
-	const root = await scanRootAt(workingDirectory, path);
 	const client = new AdminApiClient({
 		baseUrl: context.baseUrl,
 		token: await configuredApiToken(context)
@@ -3730,18 +3888,110 @@ const scanProject = async (context, path) => {
 	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 ?? []),
-		scannedLocation: root.description,
-		codeReferenceScan
+		codeReferencesIn: (root, snippetCut) => scanCodeReferences({
+			root,
+			workingDirectory,
+			include: settings?.include ?? "everyFile",
+			exclude: settings?.exclude ?? []
+		}, projectKeys, snippetCut)
+	};
+};
+//#endregion
+//#region src/scanned-repository/git-checkout.ts
+const execFileAsync = promisify(execFile);
+const firstLineOf = (text) => text.trim().split("\n")[0] ?? "";
+const gitOutput = async (directory, environmentVariables, gitArguments) => {
+	try {
+		const { stdout } = await execFileAsync("git", gitArguments, {
+			cwd: directory,
+			env: { ...environmentVariables }
+		});
+		return {
+			kind: "printed",
+			text: stdout.trim()
+		};
+	} catch (error) {
+		const failure = error;
+		return failure.code === "ENOENT" ? { kind: "git-missing" } : {
+			kind: "failed",
+			message: firstLineOf(failure.stderr ?? "")
+		};
+	}
+};
+const readGitCheckout = async (directory, environmentVariables) => {
+	const workTree = await gitOutput(directory, environmentVariables, ["rev-parse", "--is-inside-work-tree"]);
+	switch (workTree.kind) {
+		case "git-missing": return { kind: "git-missing" };
+		case "failed": return {
+			kind: "no-repository",
+			gitMessage: workTree.message
+		};
+		case "printed": break;
+	}
+	const remoteUrl = await gitOutput(directory, environmentVariables, [
+		"remote",
+		"get-url",
+		"origin"
+	]);
+	if (remoteUrl.kind !== "printed") return { kind: "no-origin-remote" };
+	const commit = await gitOutput(directory, environmentVariables, ["rev-parse", "HEAD"]);
+	return {
+		kind: "origin-remote",
+		remoteUrl: remoteUrl.text,
+		commit: commit.kind === "printed" ? commit.text : ""
+	};
+};
+//#endregion
+//#region src/scanned-repository/repository-identity.ts
+const URL_SCHEME_SEPARATOR = "://";
+const GIT_SUFFIX = ".git";
+const HTTP_PROTOCOLS = ["http:", "https:"];
+const carriesHttpCredentials = (url) => HTTP_PROTOCOLS.includes(url.protocol) && (url.username !== "" || url.password !== "");
+const withoutCredentials = (url) => {
+	const urlWithoutCredentials = new URL(url);
+	urlWithoutCredentials.username = "";
+	urlWithoutCredentials.password = "";
+	return urlWithoutCredentials.href;
+};
+const originRemoteOf = (remoteUrl) => {
+	if (!remoteUrl.includes(URL_SCHEME_SEPARATOR)) return {
+		path: remoteUrl.slice(remoteUrl.indexOf(":") + 1),
+		uploadedUrl: remoteUrl
+	};
+	const url = new URL(remoteUrl);
+	return {
+		path: url.pathname.slice(1),
+		uploadedUrl: carriesHttpCredentials(url) ? withoutCredentials(url) : remoteUrl
+	};
+};
+const repositoryNameOf = (remote) => remote.path.endsWith(GIT_SUFFIX) ? remote.path.slice(0, -4) : remote.path;
+const unnamedCheckoutReason = (checkout, scannedLocation) => {
+	switch (checkout.kind) {
+		case "git-missing": return "git is not installed or not on the PATH";
+		case "no-repository": return `git cannot read a repository in ${scannedLocation} (${checkout.gitMessage})`;
+		case "no-origin-remote": return `the git repository in ${scannedLocation} has no remote named origin`;
+	}
+};
+const unnamedRepositoryError = (checkout, scannedLocation) => new CliError(`scan --upload names the repository after its git remote origin, but ${unnamedCheckoutReason(checkout, scannedLocation)}. Name the repository with --repository <name>.`);
+const repositoryIdentityOf = (checkout, repositoryOption, scannedLocation) => {
+	if (checkout.kind === "origin-remote") {
+		const remote = originRemoteOf(checkout.remoteUrl);
+		return {
+			name: repositoryOption ?? repositoryNameOf(remote),
+			remoteUrl: remote.uploadedUrl,
+			commit: checkout.commit
+		};
+	}
+	if (repositoryOption === void 0) throw unnamedRepositoryError(checkout, scannedLocation);
+	return {
+		name: repositoryOption,
+		remoteUrl: "",
+		commit: ""
 	};
 };
 //#endregion
@@ -3758,19 +4008,20 @@ 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 }
 		};
 	}
 };
-const scanJson = (projectSlug, scan) => ({
-	project: projectSlug,
+const codeReferenceScanJson = (scan) => ({
 	filesScanned: scan.filesScanned,
 	references: scan.references.map(referenceJson),
 	dynamicReferences: scan.dynamicReferences.map((reference) => ({
@@ -3781,6 +4032,10 @@ const scanJson = (projectSlug, scan) => ({
 		argument: reference.argument
 	}))
 });
+const scanJson = (projectSlug, scan) => ({
+	project: projectSlug,
+	...codeReferenceScanJson(scan)
+});
 const DYNAMIC_REFERENCES_HEADING = "Dynamic references (calls whose key is not a string literal)";
 const withCollapsedWhitespace = (text) => {
 	let collapsed = "";
@@ -3818,11 +4073,62 @@ const scanText = (scan, scannedLocation) => {
 		counts
 	].join("\n\n")}\n`;
 };
-const scan = async (context, [path]) => {
-	const { project, scannedLocation, codeReferenceScan } = await scanProject(context, path);
+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 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, 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;
+	const { parsedBody: scannedRepository, responseBody } = await client.uploadRepositoryScan(project.id, repository.name, {
+		remoteUrl: repository.remoteUrl,
+		commit: repository.commit,
+		...codeReferenceScanJson({
+			...codeReferenceScan,
+			references: configKeyReferences
+		})
+	});
+	return {
+		json: responseBody,
+		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, snippetCut);
+	const { project, codeReferencesIn } = await connectToScannableProject(context);
+	const codeReferenceScan = await codeReferencesIn(root, snippetCut);
 	return {
 		json: scanJson(project.slug, codeReferenceScan),
-		text: scanText(codeReferenceScan, scannedLocation),
+		text: scanText(codeReferenceScan, root.description),
 		exitCode: ExitCode.success
 	};
 };
@@ -4155,14 +4461,16 @@ const validateText = (projectSlug, scan, scannedLocation, check) => {
 	}), countsText(scan, check)].join("\n\n")}\n`;
 };
 const validate = async (context, [path]) => {
-	const { project, configs, ignoredKeys, scannedLocation, codeReferenceScan } = await scanProject(context, path);
+	const root = await scanRootAt(context.invocation.workingDirectory, path);
+	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: {
 			...scanJson(project.slug, codeReferenceScan),
 			findings: check.findings.map(findingJson)
 		},
-		text: validateText(project.slug, codeReferenceScan, scannedLocation, check),
+		text: validateText(project.slug, codeReferenceScan, root.description, check),
 		exitCode: check.findings.length === 0 ? ExitCode.success : ExitCode.problemsFound
 	};
 };
@@ -4207,22 +4515,26 @@ 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").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));
 	program.command("environments").description("list the project's environments").command("list").description("list the project's environments with their slugs, marking the live ones").action(commandAction(listEnvironments));
-	const configsCommand = program.command("configs").description("list, show and create a project's configs");
+	const configsCommand = program.command("configs").description("list, show, create and archive a project's configs");
 	configsCommand.command("list").description("list the project's configs with their type, role, lifetime and lifecycle state").option("--tag <name>", "list only the configs that have this tag; repeatable, for configs with any of them", repeatedOption).addOption(new Option("--untagged", "list only the configs without tags").conflicts("tag")).addOption(new Option("--state <state>", "list only the configs in this lifecycle state").choices(LIFECYCLE_STATES)).action(commandAction(listConfigs));
 	configsCommand.command("get").argument("<key>", "the config's key, or an old key of it").description("show a config's settings and its targeting rules in every environment").action(commandAction(getConfig));
 	configsCommand.command("activity").argument("<key>", "the config's key, or an old key of it").description("show when SDKs last evaluated a config, per environment, SDK key kind, SDK name and SDK version").action(commandAction(showConfigActivity));
 	configsCommand.command("create").description("create a config from options that mirror the Admin API's fields").requiredOption("--key <key>", "the config's key (required)").option("--description <text>", "a description shown with the config in the dashboard").addOption(new Option("--type <type>", "the type of the config's values (required)").choices(CONFIG_TYPES).makeOptionMandatory()).addOption(new Option("--role <role>", "what the config is for (required)").choices(CONFIG_ROLES).makeOptionMandatory()).addOption(new Option("--lifetime <lifetime>", "whether the config is expected to be removed (required)").choices(CONFIG_LIFETIMES).makeOptionMandatory()).requiredOption("--default-value <value>", "the default targeting rule value every environment starts with, in the type given by --type; not the in-code default value an application passes to the SDK (required)").option("--client-only", "serve the config to client SDKs only (default: client and server SDKs)").addOption(new Option("--server-only", "serve the config to server SDKs only (default: client and server SDKs)").conflicts("clientOnly")).option("--tag <name>", "assign the project's tag with this name; repeatable", repeatedOption).option("--variation <name=value>", "a variation of an experiment, its value in the type given by --type; repeatable", repeatedOption).addOption(new Option("--min <number>", "the smallest value allowed, included").helpGroup(typeConstraintHelpGroup("min"))).addOption(new Option("--max <number>", "the largest value allowed, included").helpGroup(typeConstraintHelpGroup("max"))).addOption(new Option("--exclusive-min <number>", "values must be greater than this number").conflicts("min").helpGroup(typeConstraintHelpGroup("exclusiveMin"))).addOption(new Option("--exclusive-max <number>", "values must be less than this number").conflicts("max").helpGroup(typeConstraintHelpGroup("exclusiveMax"))).addOption(new Option("--unit <unit>", "the unit of the number the SDKs receive (required)").choices(TIMESPAN_UNITS).helpGroup(typeConstraintHelpGroup("unit"))).addOption(new Option("--allow-fractions", "allow values with a fraction of the unit").helpGroup(typeConstraintHelpGroup("allowFractions"))).addOption(new Option("--allowed-value <value>", "a value the config can take; repeatable").argParser(repeatedOption).helpGroup(typeConstraintHelpGroup("allowedValue"))).addOption(new Option("--enum-value-type <type>", "whether the allowed values are strings or numbers (default: string)").choices(ENUM_VALUE_TYPES).helpGroup(typeConstraintHelpGroup("enumValueType"))).addOption(new Option("--https-only", "allow only HTTPS URLs").helpGroup(typeConstraintHelpGroup("httpsOnly"))).addOption(new Option("--json-schema <file>", "a file holding the JSON Schema every value must match").helpGroup(typeConstraintHelpGroup("jsonSchema"))).action(commandAction(createConfig));
+	configsCommand.command("archive").argument("<key>", "the config's key, or an old key of it").description("archive a config, so SDKs stop receiving it; the dashboard can restore it for 30 days").addHelpText("after", "\nThe config is archived with no confirmation and no check of whether the code still reads its key, so run configdirector scan first. Applications that still read it get their in-code default value.").action(commandAction(archiveConfig));
 	const segmentsCommand = program.command("segments").description("list a project's segments and show one segment");
 	segmentsCommand.command("list").description("list the project's segments with how many configs use each").action(commandAction(listSegments));
 	segmentsCommand.command("get").argument("<key>", "the segment's key").description("show a segment's condition groups and its environment overrides").action(commandAction(getSegment));
 	const targetingRulesCommand = program.command("targeting-rules").description("replace a config's targeting rules in one environment and show the format they take");
 	targetingRulesCommand.command("set").argument("<key>", "the config's key, or an old key of it").description("replace a config's targeting rules in one environment with the rules of a JSON file").requiredOption("--environment <slug>", "slug of the environment whose targeting rules to replace (required)").requiredOption("--rules <file>", "a JSON file holding defaultValue and rules as the Admin API takes them, or - to read it from stdin (required)").addHelpText("after", "\nThe file holds {\"defaultValue\": ..., \"rules\": [...]}, like an entry of targets in configs get --json, so you can edit that output and write it back. Every rule of the environment is replaced. A rule, condition or percentage without an id gets a new one. configdirector targeting-rules reference lists the condition kinds, attributes and operators.").action(commandAction(setTargetingRules));
 	targetingRulesCommand.command("reference").description("show the format targeting rules take: the condition kinds, the attributes a condition can test and the operators").action(commandAction(showTargetingRulesReference));
+	const repositoriesCommand = program.command("repositories").description("list a project's scanned repositories and remove one");
+	repositoriesCommand.command("list").description("list the repositories whose scan was uploaded to the project, with their commit, scan time and reference counts").action(commandAction(listScannedRepositories));
+	repositoriesCommand.command("remove").argument("<name>", "the repository's name, as repositories list shows it, such as ConfigDirector/cli").description("remove a scanned repository and its code references from the project").addHelpText("after", "\nThe repository is removed with no confirmation, and the dashboard stops showing its code references. The next scan --upload from it adds it back.").action(commandAction(removeScannedRepository));
 	try {
 		await program.parseAsync(invocation.commandLineArguments, { from: "user" });
 		return exitCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@configdirector/cli",
-  "version": "0.5.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
+          }
         }
       }
     },