rtl-analyzer 0.2.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +90 -56
- package/dist/cli.js +18 -1
- package/dist/codemod.js +50 -12
- package/dist/companion-security.js +2 -0
- package/dist/contextual-preview-bridge.js +118 -0
- package/dist/contextual-preview.js +74 -0
- package/dist/controlled-apply.js +222 -0
- package/dist/css-configured-proposal.js +98 -0
- package/dist/css-directional.js +60 -0
- package/dist/css-icons.js +51 -0
- package/dist/css-spacing.js +65 -0
- package/dist/dashboard-batch-review.js +37 -0
- package/dist/dashboard-client.js +73 -50
- package/dist/dashboard-contextual-preview.js +127 -0
- package/dist/dashboard-data.js +4 -4
- package/dist/dashboard-embedded-preview.js +202 -0
- package/dist/dashboard-html.js +13 -10
- package/dist/dashboard-operation-flow.js +47 -0
- package/dist/dashboard-review-details.js +175 -0
- package/dist/dashboard-review-navigation.js +19 -0
- package/dist/dashboard-review-workflow.js +219 -0
- package/dist/dashboard-themes.js +34 -0
- package/dist/directional-properties.js +53 -0
- package/dist/discovery.js +1 -2
- package/dist/eligibility.js +8 -8
- package/dist/evidence-store.js +110 -0
- package/dist/example-preview-mappings.js +98 -0
- package/dist/manual-change-store.js +27 -0
- package/dist/migration-lifecycle.js +19 -0
- package/dist/original-preview-runtime.js +78 -0
- package/dist/output-path.js +65 -0
- package/dist/page-navigation.js +17 -0
- package/dist/policy-validation.js +7 -4
- package/dist/preview-cli.js +22 -0
- package/dist/preview-companion.js +649 -0
- package/dist/preview-configuration.js +171 -0
- package/dist/preview-runtime.js +102 -0
- package/dist/project-configuration.js +48 -0
- package/dist/project-root.js +12 -0
- package/dist/react-inline.js +65 -0
- package/dist/report-publisher.js +4 -7
- package/dist/review-approval.js +9 -0
- package/dist/review-session.js +211 -56
- package/dist/review-store.js +175 -0
- package/dist/review-workflow.js +820 -0
- package/dist/rules.js +27 -17
- package/dist/runtime-process.js +35 -0
- package/dist/scan-history.js +35 -0
- package/dist/scan-manifest-store.js +26 -0
- package/dist/scan.js +55 -4
- package/dist/scoped-direction-evidence.js +117 -0
- package/dist/serialization.js +1 -0
- package/dist/source-context.js +93 -0
- package/dist/source-snippets.js +3 -3
- package/dist/standalone-cli.js +14 -1
- package/dist/tailwind.js +3 -1
- package/dist/transformations.js +34 -0
- package/dist/validation.js +75 -0
- package/dist/workflow-validation.js +46 -0
- package/package.json +17 -8
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { proposeBidiIsolation, BIDI_TRANSFORMATION_ID } from './codemod.js';
|
|
2
|
+
import { proposeCssSpacing, CSS_SPACING_TRANSFORMATION_ID } from './css-spacing.js';
|
|
3
|
+
import { proposeCssDirectional, CSS_DIRECTIONAL_TRANSFORMATION_ID } from './css-directional.js';
|
|
4
|
+
import { proposeReactInline, REACT_INLINE_TRANSFORMATION_ID } from './react-inline.js';
|
|
5
|
+
import { proposeCssIcon, CSS_ICON_TRANSFORMATION_ID } from './css-icons.js';
|
|
6
|
+
import { CSS_CONFIGURED_TRANSFORMATION_ID, proposeConfiguredCss } from './css-configured-proposal.js';
|
|
7
|
+
/** Shared dispatch for code review, eligibility and both persisted workflows. */
|
|
8
|
+
export const transformations = [
|
|
9
|
+
{ key: 'css:explicit-intent', id: CSS_CONFIGURED_TRANSFORMATION_ID, ruleId: 'RTL.CSS.PHYSICAL', matches: (f) => !!f.cssProposal, propose: proposeConfiguredCss },
|
|
10
|
+
{ key: 'RTL.BIDI.ISOLATION:direct-text', id: BIDI_TRANSFORMATION_ID, ruleId: 'RTL.BIDI.ISOLATION', matches: (f) => f.ruleId === 'RTL.BIDI.ISOLATION', propose: proposeBidiIsolation },
|
|
11
|
+
{ key: 'RTL.CSS.PHYSICAL:spacing', id: CSS_SPACING_TRANSFORMATION_ID, ruleId: 'RTL.CSS.PHYSICAL', matches: (f) => f.ruleId === 'RTL.CSS.PHYSICAL' && f.sourceMechanism === 'css' && /^(margin|padding)-/.test(f.original), propose: proposeCssSpacing },
|
|
12
|
+
{ key: 'RTL.CSS.PHYSICAL:logical', id: CSS_DIRECTIONAL_TRANSFORMATION_ID, ruleId: 'RTL.CSS.PHYSICAL', matches: (f) => ['RTL.CSS.PHYSICAL', 'RTL.GEOMETRY.EDGE'].includes(f.ruleId) && f.sourceMechanism === 'css', propose: proposeCssDirectional },
|
|
13
|
+
{ key: 'RTL.CSS.PHYSICAL:react-inline', id: REACT_INLINE_TRANSFORMATION_ID, ruleId: 'RTL.CSS.PHYSICAL', matches: (f) => ['RTL.CSS.PHYSICAL', 'RTL.GEOMETRY.EDGE'].includes(f.ruleId) && f.sourceMechanism === 'react-inline', propose: proposeReactInline },
|
|
14
|
+
{ key: 'RTL.ICON.PROGRESSION:css-opt-in', id: CSS_ICON_TRANSFORMATION_ID, ruleId: 'RTL.ICON.PROGRESSION', matches: (f) => f.ruleId === 'RTL.ICON.PROGRESSION', propose: proposeCssIcon },
|
|
15
|
+
];
|
|
16
|
+
export function sameSupportedPatch(a, b) { return a.findingId === b.findingId && a.path === b.path && a.startOffset === b.startOffset && a.endOffset === b.endOffset && a.expectedSha256 === b.expectedSha256 && a.replacement === b.replacement; }
|
|
17
|
+
export function transformationFor(finding) { return transformations.find(t => t.matches(finding)); }
|
|
18
|
+
/** Runtime direction cannot establish semantic intent; accepted changes still need full validation. */
|
|
19
|
+
export function directionRequirement(finding) {
|
|
20
|
+
const strategy = transformationFor(finding);
|
|
21
|
+
if (!strategy)
|
|
22
|
+
return 'unknown';
|
|
23
|
+
if (strategy.id === BIDI_TRANSFORMATION_ID)
|
|
24
|
+
return 'independent';
|
|
25
|
+
if ([CSS_CONFIGURED_TRANSFORMATION_ID, CSS_SPACING_TRANSFORMATION_ID, CSS_DIRECTIONAL_TRANSFORMATION_ID, REACT_INLINE_TRANSFORMATION_ID, CSS_ICON_TRANSFORMATION_ID].some(id => id === strategy.id))
|
|
26
|
+
return 'dependent';
|
|
27
|
+
return 'unknown';
|
|
28
|
+
}
|
|
29
|
+
export function proposeTransformation(finding, source) {
|
|
30
|
+
const strategy = transformationFor(finding);
|
|
31
|
+
if (!strategy)
|
|
32
|
+
throw Error(finding.ruleId === 'RTL.UTILITY.PHYSICAL' ? 'UTILITY_COMPILER_VERSION_AND_VARIANT_REVIEW_REQUIRED' : finding.sourceMechanism === 'emotion-template' || finding.sourceMechanism === 'mui-sx' || finding.sourceMechanism === 'mui-theme' ? 'CSS_IN_JS_OWNER_AND_RTL_PROCESSOR_REVIEW_REQUIRED' : 'UNSUPPORTED_TRANSFORMATION_FAMILY');
|
|
33
|
+
return strategy.propose(finding, source);
|
|
34
|
+
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import { createHash, randomUUID } from 'node:crypto';
|
|
2
|
+
import { execFile } from 'node:child_process';
|
|
3
|
+
import { mkdir, readFile } from 'node:fs/promises';
|
|
4
|
+
import { homedir } from 'node:os';
|
|
5
|
+
import { dirname, join } from 'node:path';
|
|
6
|
+
import { fileURLToPath } from 'node:url';
|
|
7
|
+
import { promisify } from 'node:util';
|
|
8
|
+
import { chromium } from '@playwright/test';
|
|
9
|
+
import { REVIEW_SOURCE, validateReviewPath } from './review-session.js';
|
|
10
|
+
import { analyzeBidiIsolation } from './codemod.js';
|
|
11
|
+
import { sameSupportedPatch } from './transformations.js';
|
|
12
|
+
const run = promisify(execFile);
|
|
13
|
+
const sha = (x) => createHash('sha256').update(x).digest('hex');
|
|
14
|
+
const active = new Set();
|
|
15
|
+
async function scan(targetRoot, findingId) { const cli = join(dirname(fileURLToPath(import.meta.url)), 'cli.js'); let stdout = ''; try {
|
|
16
|
+
const result = await run(process.execPath, [cli, '--root', targetRoot], { cwd: targetRoot, timeout: 30_000, maxBuffer: 512_000 });
|
|
17
|
+
stdout = result.stdout;
|
|
18
|
+
}
|
|
19
|
+
catch (error) {
|
|
20
|
+
const expected = error;
|
|
21
|
+
stdout = expected.stdout ?? '';
|
|
22
|
+
if (!stdout)
|
|
23
|
+
throw new Error('SCANNER_EXECUTION_FAILED');
|
|
24
|
+
} const report = JSON.parse(stdout); if (!report.complete)
|
|
25
|
+
throw new Error('INCOMPLETE_SCAN_REQUIRES_MANUAL_RESOLUTION'); const ids = (report.findings ?? []).map(x => x.id); return { findingPresent: ids.includes(findingId), resultDigest: sha(stdout) }; }
|
|
26
|
+
export async function validateCandidate(session, finding, patch, startRuntime) { if (active.has(session.id))
|
|
27
|
+
throw new Error('VALIDATION_ALREADY_RUNNING'); active.add(session.id); const jobId = randomUUID(); const startedAt = new Date().toISOString(); try {
|
|
28
|
+
if (patch.path !== REVIEW_SOURCE || finding.id !== patch.findingId)
|
|
29
|
+
throw new Error('VALIDATION_IDENTITY_MISMATCH');
|
|
30
|
+
const originalPath = validateReviewPath(session.root, REVIEW_SOURCE);
|
|
31
|
+
const candidatePath = validateReviewPath(session.candidateRoot, REVIEW_SOURCE);
|
|
32
|
+
const original = await readFile(originalPath, 'utf8');
|
|
33
|
+
const candidate = await readFile(candidatePath, 'utf8');
|
|
34
|
+
if (sha(original) !== session.originalSha256)
|
|
35
|
+
throw new Error('STALE_ORIGINAL_SOURCE');
|
|
36
|
+
if (sha(candidate) !== session.candidateSha256)
|
|
37
|
+
throw new Error('STALE_CANDIDATE_SOURCE');
|
|
38
|
+
const proposal = analyzeBidiIsolation(finding, original);
|
|
39
|
+
if (!sameSupportedPatch(proposal.patch, patch) || candidate !== original.slice(0, patch.startOffset) + patch.replacement + original.slice(patch.endOffset))
|
|
40
|
+
throw new Error('UNSUPPORTED_CANDIDATE_PATCH');
|
|
41
|
+
const runtime = await startRuntime(session);
|
|
42
|
+
if (runtime.runtime?.status !== 'healthy')
|
|
43
|
+
throw new Error('CANDIDATE_RUNTIME_UNAVAILABLE');
|
|
44
|
+
const before = await scan(session.root, finding.id);
|
|
45
|
+
const after = await scan(session.candidateRoot, finding.id);
|
|
46
|
+
const browserErrors = [];
|
|
47
|
+
const dom = [];
|
|
48
|
+
const screenshots = [];
|
|
49
|
+
const screenshotRoot = join(homedir(), '.rtl-migration-analyzer', 'screenshots');
|
|
50
|
+
await mkdir(screenshotRoot, { recursive: true, mode: 0o700 });
|
|
51
|
+
const browser = await chromium.launch({ headless: true });
|
|
52
|
+
try {
|
|
53
|
+
for (const [label, origin, dir] of [['original-ltr', 'http://127.0.0.1:4200', 'ltr'], ['original-rtl', 'http://127.0.0.1:4200', 'rtl'], ['candidate-ltr', runtime.runtime.origin, 'ltr'], ['candidate-rtl', runtime.runtime.origin, 'rtl']]) {
|
|
54
|
+
const page = await browser.newPage({ viewport: { width: 1440, height: 1000 }, locale: 'en-US', timezoneId: 'UTC' });
|
|
55
|
+
page.on('pageerror', error => browserErrors.push(`${label}:${error.message}`));
|
|
56
|
+
const suffix = dir === 'rtl' ? '/invoices?demo=unmigrated-rtl&lang=ar' : '/invoices';
|
|
57
|
+
await page.goto(origin + suffix, { waitUntil: 'domcontentloaded', timeout: 10_000 });
|
|
58
|
+
const direction = await page.locator('html').getAttribute('dir');
|
|
59
|
+
if (direction !== (dir === 'rtl' ? 'rtl' : 'ltr'))
|
|
60
|
+
throw new Error(`DOM_DIRECTION_${label}`);
|
|
61
|
+
dom.push(`${label}:html.dir=${direction}`);
|
|
62
|
+
const image = `screenshots/${jobId}-${label}.png`;
|
|
63
|
+
await page.screenshot({ path: join(homedir(), '.rtl-migration-analyzer', image), fullPage: true });
|
|
64
|
+
screenshots.push(image);
|
|
65
|
+
await page.close();
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
finally {
|
|
69
|
+
await browser.close();
|
|
70
|
+
}
|
|
71
|
+
return { state: before.findingPresent && !after.findingPresent && browserErrors.length === 0 ? 'Passed' : 'Failed', jobId, startedAt, finishedAt: new Date().toISOString(), originalSourceSha256: sha(original), candidateSourceSha256: sha(candidate), patch, scannerBefore: before, scannerAfter: after, browserDomValidation: dom, screenshotReferences: screenshots, browserErrors, environment: { node: process.version, viewport: '1440x1000', locale: 'en-US', timezone: 'UTC' } };
|
|
72
|
+
}
|
|
73
|
+
finally {
|
|
74
|
+
active.delete(session.id);
|
|
75
|
+
} }
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
export const projectCheckNames = ['typecheck', 'build', 'test'];
|
|
2
|
+
/** Read configuration from the protected review baseline, including on historical records. */
|
|
3
|
+
export function configuredWorkflowChecks(w) {
|
|
4
|
+
const project = w.baseline['rtl-project.config.json'] ? JSON.parse(w.baseline['rtl-project.config.json']) : undefined;
|
|
5
|
+
const pkg = JSON.parse(w.baseline['package.json']);
|
|
6
|
+
return projectCheckNames.map(name => {
|
|
7
|
+
const args = project ? project.validation[name] : pkg.scripts?.[name] ? ['run', name] : undefined;
|
|
8
|
+
const excluded = project?.validationExclusions?.[name];
|
|
9
|
+
return { name, kind: 'project', state: args ? 'Not run' : excluded ? 'Not applicable' : 'Not configured',
|
|
10
|
+
command: args ? [project?.packageManager ?? 'npm', ...args].map(a => JSON.stringify(a)).join(' ') : undefined,
|
|
11
|
+
scope: 'Accepted-only candidate snapshot. The configured command determines project or subset scope.',
|
|
12
|
+
detail: args ? 'Configured command has not executed for this accepted-change snapshot.' : excluded || 'No command supplied. This does not establish whether the project has tests.' };
|
|
13
|
+
});
|
|
14
|
+
}
|
|
15
|
+
/** Required execution evidence must exist; absent records are never successful checks. */
|
|
16
|
+
export function workflowValidationEvidenceIssue(w) {
|
|
17
|
+
if (!w.validation)
|
|
18
|
+
return 'Validation has not run.';
|
|
19
|
+
if (!Array.isArray(w.validation.checks))
|
|
20
|
+
return 'Required execution records are missing. Validate accepted changes.';
|
|
21
|
+
const missing = configuredWorkflowChecks(w).filter(c => c.state === 'Not run' && !w.validation.checks.some(result => result.name === c.name && result.state !== 'Not run')).map(c => c.name);
|
|
22
|
+
if (missing.length)
|
|
23
|
+
return 'Configured checks not run: ' + missing.join(', ') + '. Validate accepted changes.';
|
|
24
|
+
if (!w.validation.checks.some(c => c.name === 'scanner') || !w.validation.checks.some(c => c.name.startsWith('runtime')))
|
|
25
|
+
return 'Required scanner or runtime execution evidence is missing. Validate accepted changes.';
|
|
26
|
+
if (Object.keys(w.baseline).some(path => !w.validation.hashes?.[path]))
|
|
27
|
+
return 'Candidate hash evidence is missing. Validate accepted changes.';
|
|
28
|
+
}
|
|
29
|
+
export function workflowValidationPresentation(w, fresh) {
|
|
30
|
+
const configured = configuredWorkflowChecks(w), results = Array.isArray(w.validation?.checks) ? w.validation.checks : [];
|
|
31
|
+
const checks = configured.map(check => {
|
|
32
|
+
if (check.state !== 'Not run')
|
|
33
|
+
return check;
|
|
34
|
+
const result = results.find(c => c.name === check.name);
|
|
35
|
+
return result ? { ...check, ...result, kind: 'project', command: check.command, scope: check.scope } : check;
|
|
36
|
+
});
|
|
37
|
+
checks.push(...(results.filter(c => !projectCheckNames.includes(c.name)).map(c => ({ ...c, kind: c.name === 'scanner' ? 'scanner' : 'runtime', scope: c.name === 'scanner' ? 'Rescan of candidate; accepted findings must resolve.' : 'Recorded mapped routes and rendered targets only; not project unit tests.' })) ?? []));
|
|
38
|
+
const projects = checks.filter(c => c.kind === 'project');
|
|
39
|
+
const ran = projects.filter(c => ['Passed', 'Failed'].includes(c.state));
|
|
40
|
+
const missing = projects.filter(c => c.state === 'Not configured');
|
|
41
|
+
const blocked = checks.filter(c => ['Failed', 'Unavailable', 'Error'].includes(c.state) && !c.name.startsWith('live-preview:'));
|
|
42
|
+
const evidenceIssue = w.validation ? workflowValidationEvidenceIssue(w) : undefined;
|
|
43
|
+
const status = !w.validation ? 'Not run' : !fresh ? 'Unavailable' : (blocked.some(c => c.state === 'Failed') || w.validation.state === 'Failed') ? 'Failed' : blocked.length || evidenceIssue || w.validation.state === 'Unavailable' ? 'Unavailable' : !ran.length ? 'Technical validation unavailable' : missing.length ? 'Limited validation' : 'Passed';
|
|
44
|
+
const explanation = !w.validation ? 'Validate accepted changes to execute checks for the exact candidate snapshot.' : !fresh ? 'Validation is stale for the accepted candidate. Validate again.' : evidenceIssue ? evidenceIssue : 'Project commands executed: ' + (ran.map(c => c.name + ' (' + c.state + ')').join(', ') || 'none') + '. ' + (missing.length ? 'Not configured: ' + missing.map(c => c.name).join(', ') + '. ' : '') + 'Scanner and runtime evidence are listed separately. Build does not imply tests or typecheck.';
|
|
45
|
+
return { status, explanation, checks, coverage: 'Unknown', coverageDetail: 'No matching change coverage evidence is available for this source, accepted candidate and executed test run. Passing tests alone do not establish finding or component coverage. Execution coverage does not prove RTL visual correctness.' };
|
|
46
|
+
}
|
package/package.json
CHANGED
|
@@ -1,17 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "rtl-analyzer",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"description": "RTL analysis with isolated review, accepted-only Apply and receipt-backed rollback",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
7
|
-
"url": "https://github.com/FoushWare/rtl-analyzer.git"
|
|
7
|
+
"url": "https://github.com/FoushWare/rtl-analyzer.git",
|
|
8
|
+
"directory": "packages/rtl-analyzer"
|
|
8
9
|
},
|
|
9
10
|
"type": "module",
|
|
10
11
|
"bin": {
|
|
11
|
-
"rtl-analyzer": "dist/standalone-cli.js"
|
|
12
|
+
"rtl-analyzer": "dist/standalone-cli.js",
|
|
13
|
+
"rtl-scanner": "dist/cli.js",
|
|
14
|
+
"rtl-preview": "dist/preview-cli.js"
|
|
12
15
|
},
|
|
13
16
|
"files": [
|
|
14
|
-
"dist
|
|
17
|
+
"dist/*.js",
|
|
15
18
|
"README.md",
|
|
16
19
|
"LICENSE"
|
|
17
20
|
],
|
|
@@ -19,7 +22,7 @@
|
|
|
19
22
|
"node": ">=22.12.0"
|
|
20
23
|
},
|
|
21
24
|
"scripts": {
|
|
22
|
-
"build": "
|
|
25
|
+
"build": "node build.mjs",
|
|
23
26
|
"prepack": "npm run build"
|
|
24
27
|
},
|
|
25
28
|
"dependencies": {
|
|
@@ -27,6 +30,12 @@
|
|
|
27
30
|
"postcss": "8.5.29",
|
|
28
31
|
"postcss-scss": "4.0.9",
|
|
29
32
|
"postcss-value-parser": "4.2.0",
|
|
30
|
-
"typescript": "~5.9.0"
|
|
31
|
-
|
|
33
|
+
"typescript": "~5.9.0",
|
|
34
|
+
"@playwright/test": "1.64.0"
|
|
35
|
+
},
|
|
36
|
+
"rtlAnalyzerImplementation": {
|
|
37
|
+
"repository": "https://github.com/FoushWare/enterprise-rtl-migration-lab",
|
|
38
|
+
"commit": "aa8873ebaee0f0c3a1448462eaf83e21a90ab89c"
|
|
39
|
+
},
|
|
40
|
+
"license": "MIT"
|
|
32
41
|
}
|