Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

Merge PR #3457: validate static carrier dependencies with the maintained TypeScript parser

haelyra64fdb301cd1a
diff --cc docs/design/context-profile-delivery.md
index 82d6151fe,82d6151fe..3b896f1da
--- a/docs/design/context-profile-delivery.md
+++ b/docs/design/context-profile-delivery.md
@@@ -89,3 -89,3 +89,7 @@@ These are attributed adaptations of con
The store recovers actual process exits at five durable boundaries: prepared journal, file publication, generation publication, receipt publication and state publication. An interruption before the initial ownership marker is published, or a corrupted partial kernel write, is preserved for inspection. These cases do not receive an automatic recovery claim.
Small authenticated Claude pilots now provide task and token observations, but they are descriptive and the evaluation gate remains `review-required`. Adequately powered task-quality canaries and whole-context measurements need additional evidence. The opt-in interactive bootstrap has local source, discovery and terminal-start evidence, but authenticated task behavior and native skill invocation remain unobserved. Isolated Codex registration, switching, refresh and rollback have local native evidence; changing a live user installation still requires its own ownership and recovery contract. Fresh-install default changes, existing-user migration, other-provider activation, hook plans, ECC Tools compatibility, hosted rollout and package publication remain outside this local preview.
++
++### Static carrier dependency gate
++
++`npm run carrier-closure:check` parses planned JavaScript files with the pinned TypeScript development parser and checks literal module references against each carrier's planned files. It executes no carrier code. Invalid source syntax fails closed; dynamic module expressions and package imports are reported separately. Literal CommonJS and ESM resolution use their distinct path rules, including ESM file URL queries and fragments. Arbitrary loader aliases and shadowed bindings are outside this static check. A successful receipt is a static closure result, while provider-native loading and execution require their own runtime evidence.
diff --cc docs/design/context-profile-delivery.tdd.md
index 725eb94a2,725eb94a2..0d4dd7f53
--- a/docs/design/context-profile-delivery.tdd.md
+++ b/docs/design/context-profile-delivery.tdd.md
@@@ -89,3 -89,3 +89,11 @@@ Current combined verification after rec
- No real AI outcome call ran because `CODEX_API_KEY` was absent. Host ChatGPT authentication was neither copied nor exposed to the disposable evaluator.
These boundaries keep the shipped behavior distinct from the M1 release gate. Authenticated outcome observations, a complete Tier 2 disk diff, live-install migration, other-provider activation, whole-context token truth and release defaults remain unverified until their explicit prerequisites are available.
++
++## October 10 carrier closure parser follow-up
++
++Independent review reproduced literal loads hidden after object-literal division and postfix increment, native `module.require` calls being skipped, and malformed source yielding a successful empty scan. The original hand-written lexer returned no dependencies for all four RED fixtures.
++
++The maintained parser in the existing pinned TypeScript development dependency now reads source without evaluating it. The gate traverses literal `require`, native `module.require`, dynamic `import`, static imports/re-exports, and literal `path.join(__dirname, ...)` calls. Existing regex, template, escape and nested-dynamic cases remain covered. Parse diagnostics fail the projection closed. ESM URL queries and fragments identify the same planned file; encoded separators and malformed escapes fail rather than normalize into a safe path.
++
++Focused validation passes 67 cases under Node 24.9.0 and Node 18.20.8. The actual CLI projects the current 304-skill registry into 10 profile/layout combinations, with 3,016 planned files, 65 JavaScript scripts and 35/35 literal relative specifiers resolved, zero escapes and zero warnings. Script execution remains deferred. Dynamic expressions are reported as warnings; arbitrary loader aliases, shadowed bindings and provider-native runtime behavior remain outside this literal-dependency gate.
diff --cc package.json
index 5b3a35594,790087013..2691cd92e
--- a/package.json
+++ b/package.json
@@@ -487,9 -472,10 +487,10 @@@
"ecc-universal": "scripts/ecc.js"
},
"scripts": {
- "welcome": "echo '\\n ecc-universal installed!\\n Run: ecc typescript\\n Compat: ecc-install typescript\\n Docs: https://github.com/affaan-m/ECC\\n Run or self-host any open-source model.\\n Compute: Itô is the preferred compute sponsor — https://compute.itomarkets.com\\n Any GPU provider works. This sponsorship link is passive: it does not invoke an RFQ, reserve capacity, provision compute, or configure serving.\\n Separately, the opt-in ecc ito find bridge invokes the explicitly configured canonical Itô CLI and submits a live authenticated RFQ; it does not reserve capacity.\\n Managed inference through Itô is not live yet.\\n'",
+ "welcome": "echo '\\n ecc-universal installed!\\n Run: ecc typescript\\n Compat: ecc-install typescript\\n Docs: https://github.com/affaan-m/ECC\\n Run or self-host any open-source model.\\n Compute: It\u00f4 is the preferred compute sponsor \u2014 https://compute.itomarkets.com\\n Any GPU provider works. This sponsorship link is passive: it does not invoke an RFQ, reserve capacity, provision compute, or configure serving.\\n Separately, the opt-in ecc ito find bridge invokes the explicitly configured canonical It\u00f4 CLI and submits a live authenticated RFQ; it does not reserve capacity.\\n Managed inference through It\u00f4 is not live yet.\\n'",
"catalog:check": "node scripts/ci/catalog.js --text",
"context-profiles:check": "node scripts/ci/validate-context-profiles.js",
+ "carrier-closure:check": "node scripts/ci/validate-carrier-closure.js",
"catalog:sync": "node scripts/ci/catalog.js --write --text",
"command-registry:generate": "node scripts/ci/generate-command-registry.js",
"command-registry:write": "node scripts/ci/generate-command-registry.js --write",
@@@ -513,13 -499,8 +514,13 @@@
"orchestrate:status": "node scripts/orchestration-status.js",
"orchestrate:worker": "bash scripts/orchestrate-codex-worker.sh",
"orchestrate:tmux": "node scripts/orchestrate-worktrees.js",
- "test:validators": "node scripts/ci/check-unicode-safety.js && node scripts/ci/validate-agents.js && node scripts/ci/validate-commands.js && node scripts/ci/validate-rules.js && node scripts/ci/validate-skills.js && node scripts/ci/validate-hooks.js && node scripts/ci/check-hooks-schema-keys.js && node scripts/ci/validate-install-manifests.js && node scripts/ci/validate-context-profiles.js && node scripts/ci/validate-no-personal-paths.js && npm run catalog:check && npm run command-registry:check",
++ "test:validators": "node scripts/ci/check-unicode-safety.js && node scripts/ci/validate-agents.js && node scripts/ci/validate-commands.js && node scripts/ci/validate-rules.js && node scripts/ci/validate-skills.js && node scripts/ci/validate-hooks.js && node scripts/ci/check-hooks-schema-keys.js && node scripts/ci/validate-install-manifests.js && node scripts/ci/validate-context-profiles.js && node scripts/ci/validate-carrier-closure.js && node scripts/ci/validate-no-personal-paths.js && npm run catalog:check && npm run command-registry:check",
+ "test:js": "node tests/run-all.js",
+ "test:python": "python3 -m pytest tests/ -q",
- "test": "node scripts/ci/check-unicode-safety.js && node scripts/ci/validate-agents.js && node scripts/ci/validate-commands.js && node scripts/ci/validate-rules.js && node scripts/ci/validate-skills.js && node scripts/ci/validate-hooks.js && node scripts/ci/check-hooks-schema-keys.js && node scripts/ci/validate-install-manifests.js && node scripts/ci/validate-context-profiles.js && node scripts/ci/validate-no-personal-paths.js && npm run catalog:check && npm run command-registry:check && node tests/run-all.js",
+ "test": "node scripts/ci/check-unicode-safety.js && node scripts/ci/validate-agents.js && node scripts/ci/validate-commands.js && node scripts/ci/validate-rules.js && node scripts/ci/validate-skills.js && node scripts/ci/validate-hooks.js && node scripts/ci/check-hooks-schema-keys.js && node scripts/ci/validate-install-manifests.js && node scripts/ci/validate-context-profiles.js && node scripts/ci/validate-carrier-closure.js && node scripts/ci/validate-no-personal-paths.js && npm run catalog:check && npm run command-registry:check && node tests/run-all.js",
- "coverage": "c8 --all --include=\"scripts/**/*.js\" --include=\"scripts/**/*.mjs\" --check-coverage --lines 80 --functions 80 --branches 79 --statements 80 --reporter=text --reporter=lcov node tests/run-all.js",
+ "coverage:js": "c8 --all --include=\"scripts/**/*.js\" --include=\"scripts/**/*.mjs\" --check-coverage --lines 80 --functions 80 --branches 80 --statements 80 --reporter=text --reporter=lcov node tests/run-all.js",
+ "coverage:python": "python3 -m pytest tests/ -q --cov=src --cov-report=term --cov-fail-under=80",
+ "coverage": "c8 --all --include=\"scripts/**/*.js\" --include=\"scripts/**/*.mjs\" --check-coverage --lines 80 --functions 80 --branches 80 --statements 80 --reporter=text --reporter=lcov node tests/run-all.js",
"build:opencode": "node scripts/build-opencode.js",
"prepack": "npm run build:opencode",
"dashboard": "python3 ./ecc_dashboard.py",
diff --cc scripts/ci/validate-carrier-closure.js
index 000000000,b6e4682db..3195a8416
mode 000000,100644..100644
--- a/scripts/ci/validate-carrier-closure.js
+++ b/scripts/ci/validate-carrier-closure.js
@@@ -1,0 -1,383 +1,228 @@@
+ #!/usr/bin/env node
+ /**
+ * Carrier runtime-closure validator.
+ *
+ * Carriers are read-only file projections. Nothing here executes a planned
- * script: every relative module specifier is extracted statically and checked
++ * script: literal require/import/export dependencies are parsed statically and checked
+ * against the planned file set of the carrier it would ship in.
+ *
+ * The static require-graph extraction technique is adapted from community
+ * PR #2788 (affaan-m/ECC). The staged load smoke from that work -- actually
+ * loading entry scripts from inside a materialized carrier -- is deliberately
+ * not ported here, and neither is command pruning.
+ */
+
+ 'use strict';
+
+ const fs = require('node:fs');
+ const path = require('node:path');
+ const { builtinModules } = require('node:module');
+ const { planContextCarrier } = require('../lib/context-carriers');
+ const { loadContextRegistry } = require('../lib/context-pack-registry');
+ const { DEFAULT_REPO_ROOT } = require('../lib/context-profile-support');
+
+ const PROFILES = Object.freeze(['lean@1', 'full@1']);
+ const BUILTINS = new Set(builtinModules);
+ const SCRIPT_EXTENSIONS = new Set(['.js', '.cjs', '.mjs']);
-const MARK = '\u0000';
-const SLOT = `${MARK}(\\d+)${MARK}`;
-// `obj.require(`, `obj?.import(` and `obj . require(` are method calls, not module loads.
-const NOT_MEMBER = '(?<!\\.\\s*)';
-const CALL_PATTERN = new RegExp(`${NOT_MEMBER}\\b(require|import)\\s*\\(\\s*${SLOT}\\s*\\)`, 'g');
-const FROM_PATTERN = new RegExp(`\\bfrom\\s*${SLOT}`, 'g');
-const SIDE_EFFECT_PATTERN = new RegExp(`\\bimport\\s*${SLOT}`, 'g');
-const DIRNAME_JOIN_PATTERN = new RegExp(
- `${NOT_MEMBER}\\brequire\\s*\\(\\s*path\\.join\\s*\\(\\s*__dirname\\s*((?:,\\s*${SLOT}\\s*)+)\\)\\s*\\)`, 'g');
-const CALL_OPEN_PATTERN = new RegExp(`${NOT_MEMBER}\\b(?:require|import)\\s*\\(`, 'g');
-const STATIC_JOIN_PATTERN = new RegExp(`^path\\.join\\s*\\(\\s*__dirname\\s*(?:,\\s*${SLOT}\\s*)+\\)$`);
-const SLOT_PATTERN = new RegExp(SLOT, 'g');
-// Closes an interpolation; no keyword pattern can match across it.
-const CLOSE = `${MARK}${MARK}`;
-const ESCAPE_PATTERN = /\\(?:u\{([0-9a-fA-F]+)\}|u([0-9a-fA-F]{4})|x([0-9a-fA-F]{2})|(\r\n|[\s\S]))/g;
-const SIMPLE_ESCAPES = Object.freeze({ n: '\n', r: '\r', t: '\t', b: '\b', f: '\f', v: '\v', 0: '\0' });
-const LINE_CONTINUATIONS = new Set(['\n', '\r', '\r\n', '\u2028', '\u2029']);
-// `}` ends a block, so a slash after it starts a statement: a regex.
-const REGEX_PRECEDES = /(?:[([{},;:=!&|?+\-*/%~^<>]|\b(?:return|typeof|case|in|of|new|delete|void|instanceof|do|else|yield|await))$/;
-const CONDITION_KEYWORD = /(?:^|[^\w$])(if|while|for|with)$/;
-
-/** Cook a raw string or template chunk the way the JavaScript parser would. */
-function decodeEscapes(raw) {
- return raw.replace(ESCAPE_PATTERN, (whole, braced, unicode, hex, other) => {
- if (braced !== undefined) {
- const codePoint = parseInt(braced, 16);
- return codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : whole;
- }
- if (unicode !== undefined) return String.fromCharCode(parseInt(unicode, 16));
- if (hex !== undefined) return String.fromCharCode(parseInt(hex, 16));
- if (LINE_CONTINUATIONS.has(other)) return '';
- return SIMPLE_ESCAPES[other] ?? other;
- });
-}
++const ts = require('typescript');
+
+ function isAbsoluteSpecifier(value) {
+ return value.startsWith('/') || value.startsWith('\\\\') || /^[A-Za-z]:[\\/]/.test(value) || /^file:/i.test(value);
+ }
+
-/**
- * Whether code ends with a keyword whose `(` opens a statement condition.
- * `obj.if(`, `obj?. while(` and `obj.` + newline + `if(` are method calls,
- * so the token before the keyword, ignoring whitespace, must not be a dot.
- */
-function opensCondition(code) {
- const match = CONDITION_KEYWORD.exec(code);
- return Boolean(match) && !code.slice(0, code.length - match[1].length).trimEnd().endsWith('.');
-}
-
-function readRegexLiteral(source, start) {
- let index = start + 1;
- let inClass = false;
- while (index < source.length) {
- const char = source[index];
- if (char === '\\') { index += 2; continue; }
- if (char === '\n') return index;
- if (char === '[') inClass = true;
- else if (char === ']') inClass = false;
- else if (char === '/' && !inClass) return index + 1;
- index += 1;
- }
- return index;
-}
-
-/**
- * Reduce source to a code skeleton in which every comment is gone and every
- * string literal is replaced by an indexed slot. A `require` shape written
- * inside a comment, a string, or a regex therefore cannot be mistaken for a
- * dependency, while `${...}` interpolations stay code.
- */
++/** Parse without evaluating source, and reject incomplete or invalid syntax. */
+ function scanSource(rawSource) {
- const source = String(rawSource || '');
- const literals = [];
- const stack = [];
- // Whether each open paren began a statement condition, and whether the
- // last one closed did: `/` after `if (...)` starts a regex, not division.
- const parens = [];
- let closedCondition = false;
- let code = '';
- let index = 0;
- // Slots cut from template literals; `from` and `import` need a quoted string.
- const templates = new Set();
- const slot = (value, fromTemplate = false) => {
- const slotIndex = literals.push(decodeEscapes(value)) - 1;
- if (fromTemplate) templates.add(slotIndex);
- code += `${MARK}${slotIndex}${MARK}`;
- };
- const frame = () => (stack.length ? stack[stack.length - 1] : null);
-
- while (index < source.length) {
- const char = source[index];
- const next = source[index + 1];
- const open = frame();
-
- if (open && open.type === 'template') {
- if (char === '\\') { open.text += source.substr(index, 2); index += 2; continue; }
- if (char === '`') { stack.pop(); slot(open.text, true); index += 1; continue; }
- if (char === '$' && next === '{') {
- slot(open.text, true);
- open.text = '';
- stack.push({ type: 'interpolation', depth: 0 });
- index += 2;
- continue;
- }
- open.text += char;
- index += 1;
- continue;
- }
- if (char === '/' && next === '/') {
- while (index < source.length && source[index] !== '\n') index += 1;
- continue;
- }
- if (char === '/' && next === '*') {
- index = source.indexOf('*/', index + 2);
- index = index === -1 ? source.length : index + 2;
- continue;
- }
- if (char === '/' && (REGEX_PRECEDES.test(code.trimEnd()) || (closedCondition && code.trimEnd().endsWith(')')))) {
- index = readRegexLiteral(source, index);
- code += ' ';
- continue;
- }
- if (char === '\'' || char === '"') {
- let cursor = index + 1;
- let value = '';
- while (cursor < source.length && source[cursor] !== char && source[cursor] !== '\n') {
- if (source[cursor] === '\\') { value += source.substr(cursor, 2); cursor += 2; continue; }
- value += source[cursor];
- cursor += 1;
- }
- slot(value);
- index = source[cursor] === char ? cursor + 1 : cursor;
- continue;
- }
- if (char === '`') { stack.push({ type: 'template', text: '' }); index += 1; continue; }
- if (open && open.type === 'interpolation') {
- if (char === '{') open.depth += 1;
- else if (char === '}') {
- if (open.depth === 0) { stack.pop(); index += 1; code += CLOSE; continue; }
- open.depth -= 1;
- }
- }
- if (char === '(') parens.push(opensCondition(code.trimEnd()));
- else if (char === ')') closedCondition = parens.pop() === true;
- code += char;
- index += 1;
++ const source = ts.createSourceFile('carrier.js', String(rawSource || ''),
++ ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
++ if (source.parseDiagnostics.length) {
++ const diagnostic = source.parseDiagnostics[0];
++ const error = new SyntaxError(ts.flattenDiagnosticMessageText(diagnostic.messageText, ' '));
++ error.position = diagnostic.start;
++ throw error;
+ }
- if (frame() && frame().type === 'template') slot(frame().text, true);
- return { code, literals, templates };
++ return source;
+ }
+
-function collect(pattern, code, handler) {
- pattern.lastIndex = 0;
- let match = pattern.exec(code);
- while (match !== null) {
- handler(match);
- match = pattern.exec(code);
- }
-}
-
-/**
- * The argument text of every `require(...)`/`import(...)` call, matched to
- * its closing paren at any nesting depth. Strings are already slots, so a
- * paren inside one cannot unbalance the count.
- */
-function callArguments(code) {
- const found = [];
- collect(CALL_OPEN_PATTERN, code, match => {
- const start = match.index + match[0].length;
- let depth = 1;
- let cursor = start;
- while (cursor < code.length && depth > 0) {
- if (code[cursor] === '(') depth += 1;
- else if (code[cursor] === ')') depth -= 1;
- cursor += 1;
- }
- if (depth === 0) found.push(code.slice(start, cursor - 1).trim());
- });
- return found;
-}
-
-function renderExpression(text, literals) {
- return text.replace(SLOT_PATTERN, (_whole, slotIndex) => `'${literals[Number(slotIndex)]}'`).split(CLOSE).join(' ').trim();
-}
-
-/**
- * Extract the relative module specifiers a script declares, plus the
- * non-literal `require`/`import` arguments that cannot be resolved without
- * running the code. `imports` lists the specifiers reached through `import()`
- * or static `import`/`from`, which Node resolves by exact path.
- */
++/** Extract literal dependencies and report dynamic expressions without execution. */
+ function extractReferences(rawSource) {
- const { code, literals, templates } = scanSource(rawSource);
- const specifiers = new Set();
- const imports = new Set();
- const packages = new Set();
- const dynamic = new Set();
-
++ const source = scanSource(rawSource);
++ const specifiers = new Set(), imports = new Set(), packages = new Set(), dynamic = new Set();
+ const record = (value, viaImport) => {
+ if (value.startsWith('.') || isAbsoluteSpecifier(value)) {
+ specifiers.add(value);
+ if (viaImport) imports.add(value);
+ } else if (!value.startsWith('node:') && !BUILTINS.has(value.split('/')[0])) {
+ packages.add(value.startsWith('@') ? value.split('/').slice(0, 2).join('/') : value.split('/')[0]);
+ }
+ };
- collect(CALL_PATTERN, code, match => record(literals[Number(match[2])], match[1] === 'import'));
- // Static `from` and side-effect `import` take only a quoted string, so a
- // template there (a tag named `from`, say) is not an import.
- for (const pattern of [FROM_PATTERN, SIDE_EFFECT_PATTERN]) {
- collect(pattern, code, match => {
- if (!templates.has(Number(match[1]))) record(literals[Number(match[1])], true);
- });
- }
- collect(DIRNAME_JOIN_PATTERN, code, match => {
- const segments = [];
- collect(SLOT_PATTERN, match[1], slotMatch => segments.push(literals[Number(slotMatch[1])]));
- specifiers.add(`./${segments.join('/')}`);
- });
- for (const argument of callArguments(code)) {
- if (!argument || new RegExp(`^${SLOT}$`).test(argument) || STATIC_JOIN_PATTERN.test(argument)) continue;
- dynamic.add(renderExpression(argument, literals));
- }
++ const identifier = (node, name) => ts.isIdentifier(node) && node.text === name;
++ const member = (node, receiver, name) => ts.isPropertyAccessExpression(node)
++ && identifier(node.expression, receiver) && node.name.text === name;
++ const literal = node => ts.isStringLiteralLike(node) ? node.text : null;
++ const staticJoin = node => {
++ if (!ts.isCallExpression(node) || !member(node.expression, 'path', 'join')
++ || !node.arguments.length || !identifier(node.arguments[0], '__dirname')) return null;
++ const parts = node.arguments.slice(1).map(literal);
++ return parts.every(value => value !== null) ? `./${parts.join('/')}` : null;
++ };
++ const visit = node => {
++ if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier) {
++ record(node.moduleSpecifier.text, true);
++ } else if (ts.isCallExpression(node)) {
++ const viaImport = node.expression.kind === ts.SyntaxKind.ImportKeyword;
++ if (viaImport || identifier(node.expression, 'require') || member(node.expression, 'module', 'require')) {
++ const argument = node.arguments[0];
++ if (argument) {
++ const value = literal(argument);
++ const joined = viaImport ? null : staticJoin(argument);
++ if (value !== null) record(value, viaImport);
++ else if (joined !== null) record(joined, false);
++ else dynamic.add(argument.getText(source));
++ }
++ }
++ }
++ ts.forEachChild(node, visit);
++ };
++ visit(source);
+ return { specifiers: [...specifiers], imports: [...imports], packages: [...packages], dynamic: [...dynamic] };
+ }
+
-/**
- * The planned paths that would satisfy a specifier, or the failure reason
- * when none can. CommonJS `require` tries the path, then `.js` and `.json`,
- * then a directory's `index.js` and `index.json` (`.cjs` and `.mjs` must be
- * named); ESM (`import`, or any `.mjs` file) resolves only the exact path.
- * A relative backslash is not a separator on Linux or macOS, so it is
- * rejected rather than normalized.
- */
+ function candidateDestinations(destinationPath, specifier, exact) {
++ if (exact && !isAbsoluteSpecifier(specifier)) {
++ // ESM resolves file URLs: query/fragment change identity, not the file path.
++ // Node rejects encoded separators; never normalize them into a safe path.
++ if (/%2f|%5c/i.test(specifier)) return { base: specifier, candidates: null, reason: 'invalid-url-separator' };
++ try { specifier = decodeURIComponent(specifier.split(/[?#]/)[0]); }
++ catch (_error) { return { base: specifier, candidates: null, reason: 'invalid-url-encoding' }; }
++ }
+ if (isAbsoluteSpecifier(specifier)) return { base: specifier, candidates: null, reason: 'outside-carrier-tree' };
+ if (specifier.includes('\\')) return { base: specifier, candidates: null, reason: 'non-portable-separator' };
+ const base = path.posix.join(path.posix.dirname(destinationPath), specifier);
+ if (base === '..' || base.startsWith('../')) return { base, candidates: null, reason: 'outside-carrier-tree' };
+ const candidates = exact
+ ? [base]
+ : [base, `${base}.js`, `${base}.json`, `${base}/index.js`, `${base}/index.json`];
+ return { base, candidates, reason: null };
+ }
+
+ function sourceReader(repoRoot) {
+ const cache = new Map();
+ return file => {
+ if (file.kind === 'generated') return file.content;
+ if (!cache.has(file.sourcePath)) {
+ cache.set(file.sourcePath, fs.readFileSync(path.join(repoRoot, ...file.sourcePath.split('/')), 'utf8'));
+ }
+ return cache.get(file.sourcePath);
+ };
+ }
+
+ function inspectProjection(carrier, profileId, read, report) {
+ const planned = new Set(carrier.files.map(file => file.destinationPath));
+ const scripts = carrier.files.filter(file => SCRIPT_EXTENSIONS.has(path.posix.extname(file.destinationPath)));
+ for (const file of scripts) {
- const { specifiers, imports, packages, dynamic } = extractReferences(read(file));
++ let references;
++ try { references = extractReferences(read(file)); }
++ catch (error) {
++ report.failures.push({ target: carrier.target, layout: carrier.layout.id, profileId,
++ file: file.destinationPath, source: file.sourcePath || null, reason: 'parse-error', diagnostic: error.message });
++ continue;
++ }
++ const { specifiers, imports, packages, dynamic } = references;
+ const exactOnly = new Set(imports);
+ const isModule = file.destinationPath.endsWith('.mjs');
+ const location = {
+ target: carrier.target, layout: carrier.layout.id, profileId,
+ file: file.destinationPath, source: file.sourcePath || null,
+ };
+ for (const specifier of specifiers) {
+ report.specifierCount += 1;
+ const exact = isModule || exactOnly.has(specifier);
+ const { base, candidates, reason } = candidateDestinations(file.destinationPath, specifier, exact);
+ if (!candidates) {
+ report.failures.push({ ...location, specifier, resolved: base, reason });
+ } else if (candidates.some(candidate => planned.has(candidate))) {
+ report.resolvedCount += 1;
+ } else {
+ report.failures.push({ ...location, specifier, resolved: base, reason: 'unplanned-target' });
+ }
+ }
+ for (const expression of dynamic) {
+ report.dynamicCount += 1;
+ report.warnings.push({ ...location, kind: 'dynamic', expression });
+ }
+ for (const name of packages) {
+ report.packageCount += 1;
+ report.warnings.push({ ...location, kind: 'package', package: name });
+ }
+ }
+ report.plannedFileCount += carrier.files.length;
+ report.scriptCount += scripts.length;
+ }
+
+ function validate(repoRoot = DEFAULT_REPO_ROOT) {
+ const registry = loadContextRegistry({ repoRoot });
+ const read = sourceReader(repoRoot);
+ const report = {
+ plannedFileCount: 0, scriptCount: 0, specifierCount: 0, resolvedCount: 0, dynamicCount: 0, packageCount: 0,
+ failures: [], warnings: [],
+ };
+ const layouts = [];
+ const unsupportedTargets = [];
+
+ for (const target of registry.targets) {
+ let supported = null;
+ for (const profileId of PROFILES) {
+ const carrier = planContextCarrier({ repoRoot, profileId, target });
+ if (!carrier.layout) break;
+ supported = { target, layout: carrier.layout.id, skillRoot: carrier.layout.skillRoot };
+ inspectProjection(carrier, profileId, read, report);
+ }
+ if (supported) layouts.push(supported); else unsupportedTargets.push(target);
+ }
+
+ return {
+ schemaVersion: 'ecc.carrier-closure.v1',
+ status: report.failures.length ? 'failure' : 'success',
+ profiles: [...PROFILES], layouts, unsupportedTargets,
+ projectionCount: layouts.length * PROFILES.length,
+ registryDigest: registry.registryDigest,
+ loadSmoke: 'deferred',
++ limitations: ['Dynamic dependency expressions and arbitrary aliases are warnings or outside this literal-dependency gate.',
++ 'Parsing does not execute scripts or certify provider-native runtime behavior.'],
+ lineage: 'static require-graph technique adapted from community PR #2788',
+ ...report,
+ };
+ }
+
+ function uniqueLines(entries, render) {
+ return [...new Set(entries.map(render))];
+ }
+
+ function main(args = process.argv.slice(2)) {
+ try {
+ for (const arg of args) {
+ if (arg !== '--json') throw new Error(`Unknown argument: ${arg}`);
+ }
+ const result = validate();
+ if (args.includes('--json')) {
+ console.log(JSON.stringify(result, null, 2));
+ } else {
+ for (const line of uniqueLines(result.warnings, w => (w.kind === 'package'
+ ? `Package import, not shipped in carriers: ${w.file} -> ${w.package}`
+ : `Dynamic require, not resolvable statically: ${w.file} -> ${w.expression}`))) {
+ console.warn(line);
+ }
+ for (const line of uniqueLines(result.failures, f => `${f.layout} ${f.profileId}: ${f.file} -> ${f.specifier} (${f.reason})`)) {
+ console.error(line);
+ }
+ console.log(`Carrier closure ${result.status}: ${result.layouts.length} layouts x ${result.profiles.length} profiles = ${result.projectionCount} projections, ${result.plannedFileCount} planned files, ${result.scriptCount} scripts, ${result.resolvedCount}/${result.specifierCount} relative specifiers resolved, ${result.failures.length} escapes, ${result.dynamicCount} dynamic requires, ${result.packageCount} package imports. Load smoke: deferred.`);
+ }
+ return result.status === 'success' ? 0 : 1;
+ } catch (error) {
+ console.error(`Carrier closure validation failed: ${error.message}`);
+ return 1;
+ }
+ }
+
+ if (require.main === module) process.exitCode = main();
+ module.exports = { extractReferences, main, scanSource, validate };
diff --cc tests/scripts/validate-carrier-closure.test.js
index 000000000,568bd342e..8624efa5b
mode 000000,100644..100644
--- a/tests/scripts/validate-carrier-closure.test.js
+++ b/tests/scripts/validate-carrier-closure.test.js
@@@ -1,0 -1,271 +1,312 @@@
+ 'use strict';
+
+ const assert = require('node:assert/strict');
+ const path = require('node:path');
+ const childProcess = require('node:child_process');
+ const test = require('node:test');
+ const { withFixture, write } = require('../lib/helpers/context-fixture');
+
+ const REPO_ROOT = path.resolve(__dirname, '../..');
+ const SCRIPT_PATH = path.join(REPO_ROOT, 'scripts/ci/validate-carrier-closure.js');
+
+ function validator() {
+ return require(SCRIPT_PATH);
+ }
+
+ let realRun = null;
+ function realRegistryRun() {
+ if (!realRun) {
+ const result = childProcess.spawnSync(process.execPath, [SCRIPT_PATH, '--json'], {
+ cwd: REPO_ROOT, encoding: 'utf8', timeout: 120_000,
+ });
+ realRun = { status: result.status, stderr: result.stderr, receipt: JSON.parse(result.stdout) };
+ }
+ return realRun;
+ }
+
+ function plantSkillScript(root, source) {
+ write(root, 'skills/ecc-guide/scripts/tool.js', source);
+ }
+
+ function specifiersOf(failures) {
+ return failures.map(failure => failure.specifier);
+ }
+
+ test('a planted require that leaves the carrier tree fails with its specifier', () => withFixture(root => {
+ const escape = '../../../../../scripts/lib/context-profile-support';
+ plantSkillScript(root, `'use strict';\n\nconst support = require('${escape}');\n\nmodule.exports = { support };\n`);
+ const result = validator().validate(root);
+ assert.equal(result.status, 'failure');
+ assert.ok(specifiersOf(result.failures).includes(escape));
+ assert.ok(result.failures.some(failure => failure.reason === 'outside-carrier-tree'));
+ assert.ok(result.failures.every(failure => failure.file.endsWith('skills/ecc-guide/scripts/tool.js')));
+ }));
+
+ test('a relative require that stays inside the tree but is unplanned fails', () => withFixture(root => {
+ plantSkillScript(root, "'use strict';\n\nrequire('../../shared/helper');\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'failure');
+ assert.ok(specifiersOf(result.failures).includes('../../shared/helper'));
+ assert.ok(result.failures.some(failure => failure.reason === 'unplanned-target'));
+ }));
+
+ test('a dynamic require warns without failing', () => withFixture(root => {
+ plantSkillScript(root, "'use strict';\n\nmodule.exports = require(process.env.ECC_PLUGIN_PATH);\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'success');
+ assert.deepEqual(result.failures, []);
+ assert.ok(result.warnings.length > 0);
+ assert.ok(result.warnings.every(warning => warning.kind === 'dynamic' && warning.expression === 'process.env.ECC_PLUGIN_PATH'));
+ assert.ok(result.warnings.every(warning => warning.file.endsWith('skills/ecc-guide/scripts/tool.js')));
+ assert.equal(result.dynamicCount, result.warnings.length);
+ }));
+
+ test('an absolute require leaves the carrier tree and fails', () => withFixture(root => {
+ plantSkillScript(root, "'use strict';\n\nrequire('/opt/shared/helper');\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'failure');
+ assert.ok(specifiersOf(result.failures).includes('/opt/shared/helper'));
+ assert.ok(result.failures.every(failure => failure.reason === 'outside-carrier-tree'));
+ }));
+
+ for (const specifier of ['C:/shared/helper', 'C:\\shared\\helper', '\\\\server\\share\\helper', 'file:///opt/helper.js']) {
+ test(`an absolute Windows or file URL require fails: ${specifier}`, () => withFixture(root => {
+ plantSkillScript(root, `'use strict';\n\nrequire(${JSON.stringify(specifier)});\n`);
+ const result = validator().validate(root);
+ assert.equal(result.status, 'failure');
+ assert.ok(result.failures.length > 0);
+ assert.ok(result.failures.every(failure => failure.reason === 'outside-carrier-tree'));
+ assert.deepEqual(result.warnings, []);
+ }));
+ }
+
+ test('a directory require resolves through index.json', () => withFixture(root => {
+ write(root, 'skills/ecc-guide/scripts/data/index.json', '{}\n');
+ plantSkillScript(root, "'use strict';\n\nmodule.exports = require('./data');\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'success', JSON.stringify(result.failures));
+ }));
+
+ // Node resolves import() and static imports by exact path: no extension
+ // search and no directory index, even when the calling file is CommonJS.
+ for (const [label, planned, source] of [
+ ['an extensionless import()', 'helper.js', "module.exports = import('./helper');\n"],
+ ['a directory import() through index.json', 'data/index.json', "module.exports = import('./data');\n"],
+ ['a directory import() through index.js', 'data/index.js', "module.exports = import('./data');\n"],
+ ['an extensionless static import', 'helper.js', "import helper from './helper';\nexport default helper;\n"],
+ ]) {
+ test(`${label} fails even when the require form would resolve`, () => withFixture(root => {
+ write(root, `skills/ecc-guide/scripts/${planned}`, planned.endsWith('.json') ? '{}\n' : 'module.exports = 1;\n');
+ plantSkillScript(root, source);
+ const result = validator().validate(root);
+ assert.equal(result.status, 'failure');
+ assert.ok(result.failures.every(failure => failure.reason === 'unplanned-target'));
+ }));
+ }
+
+ test('an import() naming the planned file exactly resolves', () => withFixture(root => {
+ write(root, 'skills/ecc-guide/scripts/helper.js', 'module.exports = 1;\n');
+ plantSkillScript(root, "module.exports = import('./helper.js');\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'success', JSON.stringify(result.failures));
+ }));
+
+ test('an extensionless require still resolves through the CommonJS extension search', () => withFixture(root => {
+ write(root, 'skills/ecc-guide/scripts/helper.js', 'module.exports = 1;\n');
+ plantSkillScript(root, "module.exports = require('./helper');\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'success', JSON.stringify(result.failures));
+ }));
+
+ // An extensionless require searches only .js, .json and .node, then a
+ // directory's index; .cjs and .mjs must be named explicitly.
+ for (const extension of ['cjs', 'mjs']) {
+ test(`an extensionless require does not resolve to a .${extension} file`, () => withFixture(root => {
+ write(root, `skills/ecc-guide/scripts/helper.${extension}`, 'module.exports = 1;\n');
+ plantSkillScript(root, "module.exports = require('./helper');\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'failure');
+ assert.ok(result.failures.every(failure => failure.reason === 'unplanned-target'));
+ }));
+ }
+
+ test('an extensionless require resolves to a .json file', () => withFixture(root => {
+ write(root, 'skills/ecc-guide/scripts/helper.json', '{}\n');
+ plantSkillScript(root, "module.exports = require('./helper');\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'success', JSON.stringify(result.failures));
+ }));
+
+ test('an object method named require is not a module load', () => withFixture(root => {
+ plantSkillScript(root, "const records = { require: name => name };\nmodule.exports = records.require('./label');\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'success', JSON.stringify(result.failures));
+ assert.deepEqual(result.warnings, []);
+ }));
+
+ test('a tagged template named from is not an import', () => withFixture(root => {
+ plantSkillScript(root, 'const from = parts => parts[0];\nmodule.exports = from`./helper`;\n');
+ const result = validator().validate(root);
+ assert.equal(result.status, 'success', JSON.stringify(result.failures));
+ assert.deepEqual(result.warnings, []);
+ }));
+
+ test('a backslash-separated relative require fails: Linux and macOS read it as one filename', () => withFixture(root => {
+ write(root, 'skills/ecc-guide/scripts/lib/helper.js', 'module.exports = 1;\n');
+ plantSkillScript(root, "module.exports = require('./lib\\\\helper.js');\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'failure');
+ assert.ok(specifiersOf(result.failures).includes('./lib\\helper.js'));
+ assert.ok(result.failures.every(failure => failure.reason === 'non-portable-separator'));
+ }));
+
+ test('a package import warns because carriers ship no node_modules; builtins do not', () => withFixture(root => {
+ plantSkillScript(root, "'use strict';\n\nconst yaml = require('js-yaml');\nconst { x } = require('@scope/pkg/deep');\n"
+ + "const fs = require('node:fs');\nconst path = require('path');\nmodule.exports = { yaml, x, fs, path };\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'success');
+ const packages = result.warnings.filter(warning => warning.kind === 'package').map(warning => warning.package);
+ assert.deepEqual([...new Set(packages)].sort(), ['@scope/pkg', 'js-yaml']);
+ assert.equal(result.packageCount, packages.length);
+ }));
+
+ test('a require shape quoted inside a string literal is not a dependency', () => withFixture(root => {
+ plantSkillScript(root, "'use strict';\n\nconst snippet = \"require('../../../../../etc/passwd')\";\n\nmodule.exports = { snippet };\n");
+ const result = validator().validate(root);
+ assert.equal(result.status, 'success');
+ assert.deepEqual(result.warnings, []);
+ }));
+
+ test('--json emits a machine-readable receipt and exits zero on a clean registry', () => {
+ const { status, stderr, receipt } = realRegistryRun();
+ assert.equal(status, 0, stderr);
+ assert.equal(receipt.schemaVersion, 'ecc.carrier-closure.v1');
+ assert.equal(receipt.projectionCount, receipt.layouts.length * receipt.profiles.length);
+ assert.ok(Array.isArray(receipt.warnings));
+ assert.ok(Number.isInteger(receipt.scriptCount));
+ assert.equal(receipt.loadSmoke, 'deferred');
+ });
+
+ test('the real registry closes: every planned script resolves inside its carrier', () => {
+ const { receipt } = realRegistryRun();
+ assert.equal(receipt.status, 'success');
+ assert.deepEqual(receipt.failures, []);
+ assert.equal(receipt.layouts.length, 5);
+ assert.deepEqual(receipt.profiles, ['lean@1', 'full@1']);
+ assert.ok(receipt.scriptCount > 0, 'expected planned JavaScript files to inspect');
+ assert.ok(receipt.resolvedCount > 0, 'expected at least one resolved relative specifier');
+ assert.ok(receipt.plannedFileCount > receipt.scriptCount);
+ });
+
+ const SCANNER_CASES = [
+ ['division before a require', "const r = a / b; require('./after-division');", ['./after-division']],
+ ['regex holding a quote', "const re = /it's/; require('./after-regex');", ['./after-regex']],
+ ['regex holding a slash in a class', "const re = /[/]/g; require('./after-class');", ['./after-class']],
+ ['regex after return', "function f() { return /x/.test(y); } require('./after-return');", ['./after-return']],
+ ['division after a closing paren', "const v = (a) / 2 / 3; require('./after-paren');", ['./after-paren']],
+ ['object braces inside an interpolation', "const s = `a ${ {k: 1}.k } b`; require('./after-template');", ['./after-template']],
+ ['require text inside a template', "const s = `require('./fake')`;", []],
+ ['require inside an interpolation', "const s = `${require('./in-interpolation')}`;", ['./in-interpolation']],
+ ['block comment', "/* require('./commented') */ require('./real');", ['./real']],
+ ['multi-line import', "import {\n a,\n b\n} from\n './multi';", ['./multi']],
+ ['re-export', 'export * from "./reexport.js";', ['./reexport.js']],
+ ['path.join from __dirname', "require(path.join(__dirname, '..', 'lib', 'x.js'));", ['./../lib/x.js']],
+ ['whitespace before the call paren', "require ('./spaced'); require\n('./newline'); import ('./spaced-import');",
+ ['./spaced', './newline', './spaced-import']],
+ ['whitespace inside path.join from __dirname', "require (path.join (__dirname, 'lib', 'y.js'));", ['./lib/y.js']],
+ ['unicode escape in a specifier', "require('\\u002e./escaped');", ['../escaped']],
+ ['hex and braced escapes in a specifier', "require('\\x2e/a'); require(`\\u{2e}/b`);", ['./a', './b']],
+ ['escaped quote and backslash', "require('./it\\'s'); require('.\\\\win');", ["./it's", '.\\win']],
+ ['regex after an if condition', "if (ok) /['\"]/.test(text); require('./missing');", ['./missing']],
+ ['regex after a while condition', "while (more) /\"/.test(s); require('./after-while');", ['./after-while']],
+ ['division after a method named if', "const v = a.if(x) / 2, q = \"/\"; require('./after-method');", ['./after-method']],
+ ['division after a call inside a condition', "if (f(a) / 2 > 1) { q = \"/\"; } require('./after-nested');", ['./after-nested']],
+ ['regex after a block', "if (ok) {} /\"/.test(text); require('./after-block');", ['./after-block']],
+ ['division after a method named if across a line break',
+ "const n = obj.\nif(x) / 2, q = \"/\"; require('./after-spaced-method');", ['./after-spaced-method']],
+ ['division after an optional-chained method named while',
+ "const n = obj?. while(x) / 2, q = \"/\"; require('./after-optional');", ['./after-optional']],
+ ['a tagged template named from', 'const from = p => p[0]; const s = from`./helper`;', []],
+ ['a template import() is still a dependency', 'import(`./templated`);', ['./templated']],
+ ['member calls named require or import',
+ "r.require('./label'); obj?.import('./x'); obj . require('./y'); obj.\nimport('./z'); require('./real');", ['./real']],
+ ];
+
+ test('scanner: computed arguments nested more than one level deep still warn', () => {
+ const { dynamic } = validator().extractReferences(
+ "require(path.join(__dirname, getName())); require(a(b(c()))); obj.require(hidden());");
+ assert.deepEqual(dynamic.sort(), ['a(b(c()))', 'path.join(__dirname, getName())']);
+ });
+
+ for (const [label, source, expected] of SCANNER_CASES) {
+ test(`scanner: ${label}`, () => {
+ assert.deepEqual(validator().extractReferences(source).specifiers.sort(), [...expected].sort());
+ });
+ }
+
+ test('scanner: an identifier named from before a template chunk is not an import', () => {
+ assert.deepEqual(validator().extractReferences('const s = `${from} is shipped as ${to}`;'),
+ { specifiers: [], imports: [], packages: [], dynamic: [] });
+ });
+
+ test('scanner: import() and static imports are reported apart from require', () => {
+ const { specifiers, imports } = validator().extractReferences(
+ "require('./a'); import('./b'); import c from './c'; import './d'; require(path.join(__dirname, 'e.js'));");
+ assert.deepEqual(specifiers.sort(), ['./a', './b', './c', './d', './e.js']);
+ assert.deepEqual(imports.sort(), ['./b', './c', './d']);
+ });
+
+ test('unknown flags are rejected', () => {
+ const result = childProcess.spawnSync(process.execPath, [SCRIPT_PATH, '--write'], {
+ cwd: REPO_ROOT, encoding: 'utf8', timeout: 120_000,
+ });
+ assert.equal(result.status, 1);
+ assert.match(result.stderr, /Unknown argument/);
+ });
+
+ test('the gate is registered in the normal test workflow', () => {
+ const { scripts } = require('../../package.json');
+ assert.equal(scripts['carrier-closure:check'], 'node scripts/ci/validate-carrier-closure.js');
+ assert.ok(scripts.test.includes('validate-carrier-closure.js'));
+ });
++
++for (const [label, source] of [
++ ['division after an object literal', "const ratio = {} / 2; require('./missing');"],
++ ['division after a postfix increment', "let i = 1; i++ / 2; require('./missing');"],
++ ['the native module.require entrypoint', "module.require('./missing');"],
++]) {
++ test(`parser: ${label} retains its literal dependency`, () => withFixture(root => {
++ plantSkillScript(root, source);
++ const result = validator().validate(root);
++ assert.equal(result.status, 'failure');
++ assert.ok(result.failures.some(failure => failure.specifier === './missing'));
++ }));
++}
++
++test('parser: malformed carrier source fails instead of producing an empty success', () => withFixture(root => {
++ plantSkillScript(root, 'const = ;');
++ const result = validator().validate(root);
++ assert.equal(result.status, 'failure');
++ assert.ok(result.failures.every(failure => failure.reason === 'parse-error'));
++}));
++
++test('parser: import options preserve the literal module dependency', () => {
++ assert.deepEqual(validator().extractReferences("import('./x.json', { with: { type: 'json' } });").imports, ['./x.json']);
++});
++
++for (const [specifier, file] of [['./helper.js?version=1#tag', 'helper.js'], ['./with%20space.js', 'with space.js']]) {
++ test(`ESM URL path resolves a planned file: ${specifier}`, () => withFixture(root => {
++ write(root, `skills/ecc-guide/scripts/${file}`, 'module.exports = 1;');
++ plantSkillScript(root, `import(${JSON.stringify(specifier)});`);
++ assert.equal(validator().validate(root).status, 'success');
++ }));
++}
++
++for (const specifier of ['./lib%2fhelper.js', './lib%5chelper.js', './invalid%zz.js']) {
++ test(`ESM invalid URL encoding fails: ${specifier}`, () => withFixture(root => {
++ plantSkillScript(root, `import(${JSON.stringify(specifier)});`);
++ const result = validator().validate(root);
++ assert.equal(result.status, 'failure');
++ assert.ok(result.failures.every(failure => failure.reason.startsWith('invalid-url-')));
++ }));
++}