Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -281,6 +281,9 @@ bundle-analysis/
.agents/
skills-lock.json

# Private pinned CODA checkout and conformance reports
.coda/

plans/

# Vitest JUnit reporter output (CI uploads it as an artifact; we don't commit it)
Expand Down
1 change: 1 addition & 0 deletions .oxfmtrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@
"ignorePatterns": [
".azure-pipelines",
".config",
".coda",
".cosmosdb-data",
".vscode-test",
"bundle-analysis",
Expand Down
1 change: 1 addition & 0 deletions .oxlintrc.jsonc
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
"ignorePatterns": [
".azure-pipelines",
".config",
".coda",
".cosmosdb-data/",
".github",
".vscode-test",
Expand Down
1 change: 1 addition & 0 deletions .vscodeignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# These files are excluded during vsce package
.cosmosdb-data/**
.coda/**
.azure-pipelines/**
.github/**
.husky/**
Expand Down
37 changes: 37 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,43 @@ There are several ways you can contribute to the [vscode-cosmosdb repository](ht

- Debug: Select the `Launch Extension` configuration in the Debug side bar and press <kbd>F5</kbd> to start debugging the extension.

### CODA conformance

`package.json.externalSpecifications.coda` pins the Git repository, tracking ref, full commit SHA and feature directory.
The SHA, not the current branch tip, determines the downloaded revision. Update the pin deliberately when adopting
another revision; normal builds and unit tests never fetch or repin CODA.

```shell
npm run fetch-coda
npm run test:coda -- --detectors DX-001,DX-011,DX-020
npm run test:coda
```

The fetch command requires Git and access to the configured private Azure DevOps repository through your existing
Git credential helper. It does not accept or store tokens in the manifest. Each commit has an isolated checkout under
`.coda`; failed downloads preserve previous checkouts, and modified caches are rejected rather than reset.
No upstream executable, Python dependency, MCP process or Azure resource collector is run.

The test command verifies the pinned checkout and compiles the original `.feature` files with Cucumber's Gherkin
compiler. TypeScript bindings prepare fixtures and call production detector evaluations and the native registry.
Bindings cover DX-001 through DX-024, including production metric/log readers and explicit acquisition failures.
The explicit subset command selects only those features; the unfiltered command selects **every** scenario and fails on
unsupported detectors, unbound steps, unsupported arguments or failed assertions. A selected subset is not a full
conformance pass. At the current pin all 379 scenarios pass, with no unbound, skipped or unexecuted scenarios.
Successful empty consumption reads count as idle for DX-004; Monitor request and embedded metric failures do not.
DX-017 accounts for arithmetic roundoff when comparing fitted growth with the inclusive 0.1 GiB/day floor.
These synthetic contract checks do not replace live collector acceptance.

The local `.coda/conformance.json` report records the source SHA, full scenario inventory and passed/failed/unbound/
not-selected counts. This report and downloaded files are private, Git-ignored, excluded from formatting/linting and
excluded from VSIX packaging. Do not upload them to public logs or artifacts. Public GitHub Actions execution is refused
unless an operator explicitly sets `CODA_TRUSTED_PRIVATE_RUNNER=1` on a genuinely trusted private runner.
Ordinary contributors without private-source access can run the infrastructure's synthetic unit tests without CODA.
`npm run test:coda-tools` checks download integrity against disposable local Git repositories.
It runs as an independent yellow `coda-tools` branch alongside magenta Vitest and cyan migration-skill tests in both
`npm run vitest` and `npm run vitest:coverage`. Parser/binding regressions do not need private-source access.
Public CI against the original contracts requires an approved redistributable upstream bundle.

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
1 change: 1 addition & 0 deletions eslint.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ export default defineConfig([
ignores: [
'.azure-pipelines',
'.config',
'.coda',
'.github',
'.vscode-test',
'coverage',
Expand Down
19 changes: 19 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

17 changes: 15 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,8 @@
"test:proxy": "node scripts/test-proxy.mjs",
"test:migration-skill": "node --test skills/cosmosdb-relational-migration/tests/*.test.mjs",
"test:shell-mcp": "cross-env COSMOSDB_SHELL_MCP_INTEGRATION=1 vitest run src/cosmosDBShell/mcpProvider.test.ts",
"vitest": "concurrently -P -n vitest,migration-skill -c magenta,cyan \"vitest run {@}\" \"npm run test:migration-skill\" --",
"vitest:coverage": "concurrently -P -n vitest,migration-skill -c magenta,cyan \"vitest run --coverage {@}\" \"npm run test:migration-skill\" --",
"vitest": "concurrently -P -n vitest,migration-skill,coda-tools -c magenta,cyan,yellow \"vitest run {@}\" \"npm run test:migration-skill\" \"npm run test:coda-tools\" --",
"vitest:coverage": "concurrently -P -n vitest,migration-skill,coda-tools -c magenta,cyan,yellow \"vitest run --coverage {@}\" \"npm run test:migration-skill\" \"npm run test:coda-tools\" --",
"vitest:ui": "vitest --ui",
"vite-dev": "rimraf ./dist && concurrently -n ext,views -c redBright,whiteBright \"npm run vite-dev-ext\" \"npm run vite-dev-wv\"",
"vite-prod": "rimraf ./dist && concurrently -n ext,views -c redBright,whiteBright \"npm run vite-prod-ext\" \"npm run vite-prod-wv\"",
Expand All @@ -91,6 +91,9 @@
"l10n:export": "npx @vscode/l10n-dev generate-xlf ./l10n/bundle.l10n.json --outFile vscode-cosmosdb.xlf",
"l10n:import": "npx @vscode/l10n-dev import-xlf ./translations.xlf",
"fetch-skill": "node scripts/fetch-skill.mjs",
"fetch-coda": "node scripts/coda.mjs fetch",
"test:coda": "node scripts/coda.mjs test",
"test:coda-tools": "node --test scripts/coda.test.mjs",
"pre-commit": "npm run build && npm run prettier-fix && npm run lint-fix && npm run l10n && npm run vitest",
"docker-up": "docker compose up -d",
"docker-down": "docker compose down",
Expand Down Expand Up @@ -118,7 +121,17 @@
]
}
},
"externalSpecifications": {
"coda": {
"repo": "https://dev.azure.com/msdata/CosmosDB/_git/CODA",
"trackingRef": "refs/heads/main",
"commit": "86549e6b118a4e88596427fb5c008a9bc0570928",
"featurePath": "specs/detectors"
}
},
"devDependencies": {
"@cucumber/gherkin": "~42.0.1",
"@cucumber/messages": "~34.2.1",
"@playwright/test": "~1.64.0",
"@testing-library/jest-dom": "~7.0.0",
"@testing-library/react": "~16.3.2",
Expand Down
204 changes: 204 additions & 0 deletions scripts/coda.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
#!/usr/bin/env node

/*---------------------------------------------------------------------------------------------
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License. See License.txt in the project root for license information.
*--------------------------------------------------------------------------------------------*/

import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const root = fileURLToPath(new URL('../', import.meta.url));

export function readCodaPin(manifest) {
const config = manifest.externalSpecifications?.coda;
if (
!config ||
typeof config.repo !== 'string' ||
!/^https:\/\/[^/@]+\/[^?#]+$/.test(config.repo) ||
!/^[a-f0-9]{40}$/.test(config.commit ?? '') ||
!/^refs\/heads\/[A-Za-z0-9._/-]+$/.test(config.trackingRef ?? '') ||
typeof config.featurePath !== 'string' ||
!/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(config.featurePath)
) {
throw new Error(
'Invalid externalSpecifications.coda pin: expected HTTPS repository, full SHA, tracking ref and relative feature path.',
);
}
return config;
}

function git(directory, args) {
const result = spawnSync('git', ['--no-pager', '-C', directory, ...args], {
encoding: 'utf8',
timeout: 180_000,
maxBuffer: 8 * 1024 * 1024,
env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
windowsHide: true,
});
if (result.error || result.status !== 0) {
throw new Error(`CODA Git operation failed (${args[0]}): ${result.error?.message ?? result.stderr.trim()}`);
}
return result.stdout.trim();
}

export function featureFiles(directory) {
const result = [];
for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
const file = path.join(directory, entry.name);
if (entry.isSymbolicLink()) {
throw new Error('CODA feature paths must not contain symbolic links.');
}
if (entry.isDirectory()) {
result.push(...featureFiles(file));
} else if (entry.isFile() && entry.name.endsWith('.feature')) {
result.push(file);
}
}
return result;
}

function verifyCheckout(directory, pin) {
if (lstatSync(directory).isSymbolicLink()) {
throw new Error('CODA cache must not be a symbolic link.');
}
if (git(directory, ['rev-parse', 'HEAD']) !== pin.commit) {
throw new Error('CODA cache HEAD does not match the pinned commit.');
}
if (git(directory, ['config', '--get', 'remote.origin.url']) !== pin.repo) {
throw new Error('CODA cache origin does not match the pinned repository.');
}
if (git(directory, ['status', '--porcelain', '--untracked-files=all', '--ignored=matching']) !== '') {
throw new Error(
'CODA cache has local changes. Preserve them elsewhere before removing this named cache entry.',
);
}
const parts = pin.featurePath.split('/');
let featureRoot = directory;
for (const part of parts) {
featureRoot = path.join(featureRoot, part);
if (lstatSync(featureRoot).isSymbolicLink()) {
throw new Error('CODA feature directory must not be a symbolic link.');
}
}
const files = featureFiles(featureRoot);
if (files.length === 0) {
throw new Error('The pinned CODA revision contains no feature files.');
}
return featureRoot;
}

export function fetchCoda(pin, cacheRoot = path.join(root, '.coda')) {
mkdirSync(cacheRoot, { recursive: true });
if (lstatSync(cacheRoot).isSymbolicLink()) {
throw new Error('CODA cache root must not be a symbolic link.');
}
const identity = createHash('sha256').update(pin.repo).digest('hex').slice(0, 12);
const destination = path.join(cacheRoot, `${identity}-${pin.commit}`);
if (existsSync(destination)) {
return verifyCheckout(destination, pin);
}
const staging = mkdtempSync(path.join(cacheRoot, 'fetch-'));
try {
git(staging, ['init', '--quiet']);
git(staging, ['config', 'core.autocrlf', 'false']);
git(staging, ['remote', 'add', 'origin', pin.repo]);
// Fetch the object, not mutable main. No submodules, hooks or upstream executables are run.
git(staging, [
'-c',
'credential.interactive=never',
'fetch',
'--quiet',
'--depth=1',
'--no-tags',
'origin',
pin.commit,
]);
git(staging, ['-c', 'core.hooksPath=', 'checkout', '--quiet', '--detach', pin.commit]);
verifyCheckout(staging, pin);
renameSync(staging, destination);
} finally {
if (existsSync(staging)) {
rmSync(staging, { recursive: true, force: true });
}
}
return verifyCheckout(destination, pin);
}

export function parseArguments(args) {
const [command, ...options] = args;
if (!['fetch', 'test'].includes(command)) {
throw new Error('Usage: node scripts/coda.mjs fetch|test [--detectors DX-001,DX-011,DX-020]');
}
let detectors;
if (options.length > 0) {
if (command !== 'test' || options.length !== 2 || options[0] !== '--detectors') {
throw new Error('Only test supports --detectors followed by a comma-separated detector list.');
}
detectors = options[1].split(',');
if (
detectors.length === 0 ||
detectors.some((id) => !/^DX-\d{3}$/.test(id)) ||
new Set(detectors).size !== detectors.length
) {
throw new Error('Invalid or duplicate detector selection.');
}
}
return { command, detectors };
}

export function main(args = process.argv.slice(2)) {
const { command, detectors } = parseArguments(args);
if (process.env.GITHUB_ACTIONS === 'true' && process.env.CODA_TRUSTED_PRIVATE_RUNNER !== '1') {
throw new Error(
'Private CODA sources/reports must not enter public Actions logs. Use a trusted private runner with CODA_TRUSTED_PRIVATE_RUNNER=1.',
);
}
const manifest = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
const pin = readCodaPin(manifest);
const features = fetchCoda(pin);
console.log(`CODA commit: ${pin.commit}; feature files: ${featureFiles(features).length}`);
if (command === 'fetch') {
console.log('Pinned checkout verified. No tests or upstream code executed.');
return 0;
}
const report = path.join(root, '.coda', 'conformance.json');
rmSync(report, { force: true });
const result = spawnSync(
process.execPath,
[
path.join(root, 'node_modules', 'vitest', 'vitest.mjs'),
'run',
'--config',
path.join(root, 'vitest.coda.config.ts'),
],
{
cwd: root,
stdio: 'inherit',
env: {
...process.env,
CODA_FEATURE_ROOT: features,
CODA_COMMIT: pin.commit,
CODA_DETECTORS: detectors?.join(',') ?? '',
CODA_REPORT: report,
},
windowsHide: true,
},
);
if (result.error) {
throw result.error;
}
return result.status ?? 1;
}

if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
try {
process.exitCode = main();
} catch (error) {
console.error(error instanceof Error ? error.message : String(error));
process.exitCode = 1;
}
}
Loading
Loading