hvigor-dependency-policy-plugin 0.2.0-beta

package/README.md

@@ -0,0 +1,82 @@
+# hvigor-dependency-policy-plugin v2
+
+This version no longer rewrites Hvigor dependency context in memory.
+It materializes the selected dependency policy into the project-level `oh-package.json5` `overrides` field.
+
+That means DevEco Sync, OHPM, lock files, and the build process can see the same static dependency declaration.
+
+## Usage
+
+```ts
+// root hvigorfile.ts
+import { appTasks } from '@ohos/hvigor-ohos-plugin';
+import { dependencyPolicyPlugin } from '@didi/hvigor-dependency-policy-plugin';
+
+export default {
+  system: appTasks,
+  plugins: [
+    dependencyPolicyPlugin({
+      profile: 'stable',
+      dryRun: false,
+      logLevel: 'debug'
+    })
+  ]
+};
+```
+
+You can also select the profile with an environment variable:
+
+```bash
+DEP_POLICY_PROFILE=gray ./hvigorw --sync
+DEP_POLICY_PROFILE=gray ./hvigorw assembleApp --no-daemon
+```
+
+## Configuration
+
+By default the plugin reads:
+
+```text
+<pluginRoot>/config/dependency-policy.json5
+```
+
+You can override it:
+
+```ts
+dependencyPolicyPlugin({
+  configPath: './config/dependency-policy.json5'
+})
+```
+
+## Schema v2
+
+```json5
+{
+  schemaVersion: 2,
+  defaultProfile: 'stable',
+  conflictPolicy: 'warn',
+  pathBase: 'projectRoot',
+  report: true,
+  profiles: {
+    stable: {
+      app: {
+        strategy: 'merge',
+        overrides: {
+          '@company/core': '2.4.0',
+          '@company/logger': 'file:./libs/logger.har'
+        },
+        remove: {
+          overrides: ['@company/legacy-core']
+        }
+      }
+    }
+  }
+}
+```
+
+## Notes
+
+- `strategy: 'merge'` keeps existing project overrides and adds/updates the policy items.
+- `strategy: 'replace'` rewrites the whole `overrides` object.
+- `file:` paths are written relative to the project root so they are valid inside project-level `oh-package.json5`.
+- Module-level `profiles.<profile>.modules` rules are intentionally ignored in v2. Move dependency versions that should be forced globally into `profiles.<profile>.app.overrides`.
+- A report is written to `build/dependency-policy/overrides-report.json`.

package/config/dependency-policy.json5

@@ -0,0 +1,44 @@
+{
+  schemaVersion: 2,
+
+  // If dependencyPolicyPlugin({ profile }) and DEP_POLICY_PROFILE are both absent,
+  // this profile will be used.
+  defaultProfile: "stable",
+
+  // pluginWins | projectWins | warn | error
+  conflictPolicy: "warn",
+
+  // projectRoot | configFile | pluginRoot
+  pathBase: "projectRoot",
+
+  // Write build/dependency-policy/overrides-report.json
+  report: true,
+
+  profiles: {
+    stable: {
+      app: {
+        // merge keeps existing project overrides. replace rewrites the whole overrides object.
+        strategy: "merge",
+
+        overrides: {
+          "@didi-wyc/quality": "1.0.20",
+          
+        },
+
+        remove: {
+          overrides: [
+          ]
+        }
+      }
+    },
+
+    gray: {
+      app: {
+        strategy: "merge",
+        overrides: {
+ 
+        }
+      }
+    }
+  }
+}

package/dist/diff.d.ts

@@ -0,0 +1,6 @@
+import type { DependencyMap, OverridesDiff } from './types';
+export declare function diffOverrides(before: DependencyMap, after: DependencyMap, keptByProjectWins: Record<string, {
+    project: string;
+    plugin: string;
+}>): OverridesDiff;
+export declare function hasOverridesDiff(diff: OverridesDiff): boolean;

package/dist/diff.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffOverrides = diffOverrides;
+exports.hasOverridesDiff = hasOverridesDiff;
+function diffOverrides(before, after, keptByProjectWins) {
+    const added = {};
+    const changed = {};
+    const removed = {};
+    for (const [name, afterValue] of Object.entries(after)) {
+        if (before[name] === undefined) {
+            added[name] = afterValue;
+        }
+        else if (before[name] !== afterValue) {
+            changed[name] = {
+                from: before[name],
+                to: afterValue
+            };
+        }
+    }
+    for (const [name, beforeValue] of Object.entries(before)) {
+        if (after[name] === undefined) {
+            removed[name] = beforeValue;
+        }
+    }
+    return {
+        before,
+        after,
+        added,
+        changed,
+        removed,
+        keptByProjectWins
+    };
+}
+function hasOverridesDiff(diff) {
+    return (Object.keys(diff.added).length > 0 ||
+        Object.keys(diff.changed).length > 0 ||
+        Object.keys(diff.removed).length > 0 ||
+        Object.keys(diff.keptByProjectWins).length > 0);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { DependencyMap, OverridesDiff } from './types';
+export declare function diffOverrides(before: DependencyMap, after: DependencyMap, keptByProjectWins: Record<string, {
+    project: string;
+    plugin: string;
+}>): OverridesDiff;
+export declare function hasOverridesDiff(diff: OverridesDiff): boolean;

package/dist/index.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffOverrides = diffOverrides;
+exports.hasOverridesDiff = hasOverridesDiff;
+function diffOverrides(before, after, keptByProjectWins) {
+    const added = {};
+    const changed = {};
+    const removed = {};
+    for (const [name, afterValue] of Object.entries(after)) {
+        if (before[name] === undefined) {
+            added[name] = afterValue;
+        }
+        else if (before[name] !== afterValue) {
+            changed[name] = {
+                from: before[name],
+                to: afterValue
+            };
+        }
+    }
+    for (const [name, beforeValue] of Object.entries(before)) {
+        if (after[name] === undefined) {
+            removed[name] = beforeValue;
+        }
+    }
+    return {
+        before,
+        after,
+        added,
+        changed,
+        removed,
+        keptByProjectWins
+    };
+}
+function hasOverridesDiff(diff) {
+    return (Object.keys(diff.added).length > 0 ||
+        Object.keys(diff.changed).length > 0 ||
+        Object.keys(diff.removed).length > 0 ||
+        Object.keys(diff.keptByProjectWins).length > 0);
+}

package/dist/logger.d.ts

@@ -0,0 +1,11 @@
+import type { LogLevel } from './types';
+export declare class Logger {
+    private readonly level;
+    constructor(level?: LogLevel);
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    fatal(message: string, data?: unknown): void;
+    private write;
+}

package/dist/logger.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const LEVEL_WEIGHT = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    silent: 100
+};
+class Logger {
+    constructor(level = 'info') {
+        this.level = level;
+    }
+    debug(message, data) {
+        this.write('debug', message, data);
+    }
+    info(message, data) {
+        this.write('info', message, data);
+    }
+    warn(message, data) {
+        this.write('warn', message, data);
+    }
+    error(message, data) {
+        this.write('error', message, data);
+    }
+    fatal(message, data) {
+        this.write('error', message, data);
+    }
+    write(level, message, data) {
+        if (LEVEL_WEIGHT[level] < LEVEL_WEIGHT[this.level]) {
+            return;
+        }
+        const prefix = `[dependency-policy] ${level.toUpperCase()}: ${message}`;
+        if (data === undefined) {
+            console.error(prefix);
+            return;
+        }
+        try {
+            console.error(prefix, JSON.stringify(data, null, 2));
+        }
+        catch (_error) {
+            console.error(prefix, data);
+        }
+    }
+}
+exports.Logger = Logger;

package/dist/oh-package-editor.d.ts

@@ -0,0 +1,10 @@
+import type { DependencyMap } from './types';
+export interface ProjectOhPackage {
+    path: string;
+    text: string;
+    data: Record<string, unknown>;
+    overrides: DependencyMap;
+}
+export declare function readProjectOhPackage(projectOhPackagePath: string): ProjectOhPackage;
+export declare function writeProjectOverrides(projectOhPackagePath: string, originalText: string, overrides: DependencyMap, backup: boolean): boolean;
+export declare function normalizeDependencyMap(value: unknown): DependencyMap;

package/dist/oh-package-editor.js

@@ -0,0 +1,296 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readProjectOhPackage = readProjectOhPackage;
+exports.writeProjectOverrides = writeProjectOverrides;
+exports.normalizeDependencyMap = normalizeDependencyMap;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const json5_1 = __importDefault(require("json5"));
+function readProjectOhPackage(projectOhPackagePath) {
+    if (!fs_1.default.existsSync(projectOhPackagePath)) {
+        throw new Error(`[dependency-policy] project oh-package.json5 not found: ${projectOhPackagePath}`);
+    }
+    const text = fs_1.default.readFileSync(projectOhPackagePath, 'utf-8');
+    const data = json5_1.default.parse(text);
+    const overrides = normalizeDependencyMap(data.overrides);
+    return {
+        path: projectOhPackagePath,
+        text,
+        data,
+        overrides
+    };
+}
+function writeProjectOverrides(projectOhPackagePath, originalText, overrides, backup) {
+    const nextText = updateTopLevelObjectProperty(originalText, 'overrides', overrides);
+    if (nextText === originalText) {
+        return false;
+    }
+    if (backup) {
+        const backupPath = `${projectOhPackagePath}.dependency-policy.bak`;
+        if (!fs_1.default.existsSync(backupPath)) {
+            fs_1.default.writeFileSync(backupPath, originalText, 'utf-8');
+        }
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(projectOhPackagePath), { recursive: true });
+    fs_1.default.writeFileSync(projectOhPackagePath, nextText, 'utf-8');
+    return true;
+}
+function normalizeDependencyMap(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    const result = {};
+    for (const [key, itemValue] of Object.entries(value)) {
+        if (typeof itemValue === 'string') {
+            result[key] = itemValue;
+        }
+    }
+    return result;
+}
+function updateTopLevelObjectProperty(text, propertyName, value) {
+    const rootOpen = findFirstNonCommentChar(text, '{', 0);
+    if (rootOpen < 0) {
+        throw new Error('[dependency-policy] invalid oh-package.json5: root object not found.');
+    }
+    const rootClose = findMatchingBracket(text, rootOpen);
+    if (rootClose < 0) {
+        throw new Error('[dependency-policy] invalid oh-package.json5: root object is not closed.');
+    }
+    const propertyRange = findTopLevelProperty(text, rootOpen, rootClose, propertyName);
+    if (propertyRange) {
+        const propertyIndent = getLineIndent(text, propertyRange.propertyStart);
+        const renderedValue = renderDependencyMap(value, propertyIndent);
+        return text.slice(0, propertyRange.valueStart) + renderedValue + text.slice(propertyRange.valueEnd);
+    }
+    const rootIndent = getLineIndent(text, rootOpen);
+    const propertyIndent = `${rootIndent}  `;
+    const renderedValue = renderDependencyMap(value, propertyIndent);
+    const beforeClose = text.slice(rootOpen + 1, rootClose);
+    const hasExistingProperties = beforeClose.trim().length > 0;
+    const lastContentIndex = findLastNonWhitespaceIndex(text, rootOpen + 1, rootClose);
+    const needsComma = hasExistingProperties && lastContentIndex >= 0 && text[lastContentIndex] !== ',';
+    const insertion = hasExistingProperties
+        ? `${needsComma ? ',' : ''}\n${propertyIndent}${propertyName}: ${renderedValue}\n`
+        : `\n${propertyIndent}${propertyName}: ${renderedValue}\n`;
+    return text.slice(0, rootClose) + insertion + text.slice(rootClose);
+}
+function findTopLevelProperty(text, rootOpen, rootClose, targetName) {
+    let index = rootOpen + 1;
+    while (index < rootClose) {
+        index = skipWhitespaceAndComments(text, index, rootClose);
+        if (index >= rootClose || text[index] === '}') {
+            break;
+        }
+        const propertyStart = index;
+        const nameResult = readPropertyName(text, index, rootClose);
+        if (!nameResult) {
+            index += 1;
+            continue;
+        }
+        index = skipWhitespaceAndComments(text, nameResult.end, rootClose);
+        if (text[index] !== ':') {
+            index += 1;
+            continue;
+        }
+        const valueStart = skipWhitespaceAndComments(text, index + 1, rootClose);
+        const valueEnd = readValueEnd(text, valueStart, rootClose);
+        if (nameResult.name === targetName) {
+            return {
+                propertyStart,
+                valueStart,
+                valueEnd
+            };
+        }
+        index = valueEnd;
+        if (text[index] === ',') {
+            index += 1;
+        }
+    }
+    return undefined;
+}
+function readPropertyName(text, start, end) {
+    const char = text[start];
+    if (char === '"' || char === "'") {
+        const stringEnd = readStringEnd(text, start, end);
+        const raw = text.slice(start, stringEnd);
+        try {
+            return {
+                name: json5_1.default.parse(raw),
+                end: stringEnd
+            };
+        }
+        catch (_error) {
+            return undefined;
+        }
+    }
+    if (!/[A-Za-z_$]/.test(char)) {
+        return undefined;
+    }
+    let index = start + 1;
+    while (index < end && /[A-Za-z0-9_$-]/.test(text[index])) {
+        index += 1;
+    }
+    return {
+        name: text.slice(start, index),
+        end: index
+    };
+}
+function readValueEnd(text, start, hardEnd) {
+    if (start >= hardEnd) {
+        return start;
+    }
+    const first = text[start];
+    if (first === '{' || first === '[') {
+        const bracketEnd = findMatchingBracket(text, start);
+        return bracketEnd >= 0 ? bracketEnd + 1 : hardEnd;
+    }
+    if (first === '"' || first === "'") {
+        return readStringEnd(text, start, hardEnd);
+    }
+    let index = start;
+    while (index < hardEnd) {
+        const char = text[index];
+        if (char === ',' || char === '}') {
+            break;
+        }
+        if (char === '/' && text[index + 1] === '/') {
+            index = skipLineComment(text, index + 2, hardEnd);
+            continue;
+        }
+        if (char === '/' && text[index + 1] === '*') {
+            index = skipBlockComment(text, index + 2, hardEnd);
+            continue;
+        }
+        index += 1;
+    }
+    return trimRightIndex(text, start, index);
+}
+function findMatchingBracket(text, openIndex) {
+    const openChar = text[openIndex];
+    const closeChar = openChar === '{' ? '}' : openChar === '[' ? ']' : undefined;
+    if (!closeChar) {
+        return -1;
+    }
+    let depth = 0;
+    let index = openIndex;
+    while (index < text.length) {
+        const char = text[index];
+        if (char === '"' || char === "'") {
+            index = readStringEnd(text, index, text.length);
+            continue;
+        }
+        if (char === '/' && text[index + 1] === '/') {
+            index = skipLineComment(text, index + 2, text.length);
+            continue;
+        }
+        if (char === '/' && text[index + 1] === '*') {
+            index = skipBlockComment(text, index + 2, text.length);
+            continue;
+        }
+        if (char === openChar) {
+            depth += 1;
+        }
+        else if (char === closeChar) {
+            depth -= 1;
+            if (depth === 0) {
+                return index;
+            }
+        }
+        index += 1;
+    }
+    return -1;
+}
+function findFirstNonCommentChar(text, expected, start) {
+    let index = start;
+    while (index < text.length) {
+        index = skipWhitespaceAndComments(text, index, text.length);
+        if (text[index] === expected) {
+            return index;
+        }
+        if (index >= text.length) {
+            return -1;
+        }
+        index += 1;
+    }
+    return -1;
+}
+function skipWhitespaceAndComments(text, start, end) {
+    let index = start;
+    while (index < end) {
+        while (index < end && /\s/.test(text[index])) {
+            index += 1;
+        }
+        if (text[index] === '/' && text[index + 1] === '/') {
+            index = skipLineComment(text, index + 2, end);
+            continue;
+        }
+        if (text[index] === '/' && text[index + 1] === '*') {
+            index = skipBlockComment(text, index + 2, end);
+            continue;
+        }
+        break;
+    }
+    return index;
+}
+function skipLineComment(text, start, end) {
+    let index = start;
+    while (index < end && text[index] !== '\n') {
+        index += 1;
+    }
+    return index;
+}
+function skipBlockComment(text, start, end) {
+    const close = text.indexOf('*/', start);
+    return close >= 0 && close < end ? close + 2 : end;
+}
+function readStringEnd(text, start, end) {
+    const quote = text[start];
+    let index = start + 1;
+    while (index < end) {
+        if (text[index] === '\\') {
+            index += 2;
+            continue;
+        }
+        if (text[index] === quote) {
+            return index + 1;
+        }
+        index += 1;
+    }
+    return end;
+}
+function trimRightIndex(text, start, end) {
+    let index = end;
+    while (index > start && /\s/.test(text[index - 1])) {
+        index -= 1;
+    }
+    return index;
+}
+function findLastNonWhitespaceIndex(text, start, end) {
+    let index = end - 1;
+    while (index >= start && /\s/.test(text[index])) {
+        index -= 1;
+    }
+    return index;
+}
+function getLineIndent(text, index) {
+    const lineStart = text.lastIndexOf('\n', index - 1) + 1;
+    const match = /^[ \t]*/.exec(text.slice(lineStart, index));
+    return match ? match[0] : '';
+}
+function renderDependencyMap(value, propertyIndent) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+        return '{}';
+    }
+    const childIndent = `${propertyIndent}  `;
+    const lines = ['{'];
+    entries.forEach(([key, itemValue], index) => {
+        const comma = index === entries.length - 1 ? '' : ',';
+        lines.push(`${childIndent}${JSON.stringify(key)}: ${JSON.stringify(itemValue)}${comma}`);
+    });
+    lines.push(`${propertyIndent}}`);
+    return lines.join('\n');
+}

package/dist/overrides-applier.d.ts

@@ -0,0 +1,9 @@
+import type { DependencyMap, LoadedPolicyConfig, OverridesDiff } from './types';
+import type { Logger } from './logger';
+export interface BuildOverridesResult {
+    after: DependencyMap;
+    diff: OverridesDiff;
+    warnings: string[];
+}
+export declare function buildProjectOverrides(before: DependencyMap, loaded: LoadedPolicyConfig, profileName: string, projectRoot: string, logger: Logger): BuildOverridesResult;
+export declare function resolveProjectOhPackagePath(projectRoot: string, loaded: LoadedPolicyConfig, projectOhPackagePath?: string): string;

package/dist/overrides-applier.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildProjectOverrides = buildProjectOverrides;
+exports.resolveProjectOhPackagePath = resolveProjectOhPackagePath;
+const path_1 = __importDefault(require("path"));
+const path_utils_1 = require("./path-utils");
+const diff_1 = require("./diff");
+function buildProjectOverrides(before, loaded, profileName, projectRoot, logger) {
+    const config = loaded.config;
+    const profile = config.profiles[profileName];
+    const appRule = profile.app ?? {};
+    const warnings = [];
+    if (profile.modules && Object.keys(profile.modules).length > 0) {
+        const warning = `profile "${profileName}" contains modules rules, but schemaVersion 2 only materializes ` +
+            'project-level oh-package.json5 overrides. Move desired dependency versions into profiles.<name>.app.overrides.';
+        warnings.push(warning);
+        logger.warn(warning);
+    }
+    const env = {
+        projectRoot,
+        configDir: loaded.configDir,
+        pluginRoot: loaded.pluginRoot,
+        pathBase: config.pathBase ?? 'projectRoot',
+        conflictPolicy: config.conflictPolicy ?? 'warn'
+    };
+    const after = applyAppRule(before, appRule, env, logger, warnings);
+    const keptByProjectWins = collectKeptByProjectWins(before, appRule, env);
+    const diff = (0, diff_1.diffOverrides)(before, after, keptByProjectWins);
+    return {
+        after,
+        diff,
+        warnings
+    };
+}
+function applyAppRule(before, rule, env, logger, warnings) {
+    const strategy = rule.strategy ?? 'merge';
+    const next = strategy === 'replace' ? {} : { ...before };
+    for (const packageName of rule.remove?.overrides ?? []) {
+        delete next[packageName];
+    }
+    for (const [packageName, rawValue] of Object.entries(rule.overrides ?? {})) {
+        const pluginValue = (0, path_utils_1.normalizeDependencyValueForProjectOhPackage)(rawValue, env, rule.pathBase);
+        const projectValue = before[packageName];
+        if (projectValue !== undefined && projectValue !== pluginValue) {
+            const decision = handleConflict(packageName, projectValue, pluginValue, env.conflictPolicy, logger, warnings);
+            if (decision === 'keepProject') {
+                next[packageName] = projectValue;
+                continue;
+            }
+        }
+        next[packageName] = pluginValue;
+    }
+    return next;
+}
+function collectKeptByProjectWins(before, rule, env) {
+    const result = {};
+    if (env.conflictPolicy !== 'projectWins') {
+        return result;
+    }
+    for (const [packageName, rawValue] of Object.entries(rule.overrides ?? {})) {
+        const pluginValue = (0, path_utils_1.normalizeDependencyValueForProjectOhPackage)(rawValue, env, rule.pathBase);
+        const projectValue = before[packageName];
+        if (projectValue !== undefined && projectValue !== pluginValue) {
+            result[packageName] = {
+                project: projectValue,
+                plugin: pluginValue
+            };
+        }
+    }
+    return result;
+}
+function handleConflict(packageName, projectValue, pluginValue, conflictPolicy, logger, warnings) {
+    const message = `override conflict for ${packageName}: project oh-package.json5 has ${projectValue}, ` +
+        `policy wants ${pluginValue}.`;
+    switch (conflictPolicy) {
+        case 'pluginWins':
+            return 'usePlugin';
+        case 'projectWins':
+            logger.info(`${message} Keep project value because conflictPolicy=projectWins.`);
+            return 'keepProject';
+        case 'warn': {
+            const warning = `${message} Use policy value because conflictPolicy=warn.`;
+            warnings.push(warning);
+            logger.warn(warning);
+            return 'usePlugin';
+        }
+        case 'error':
+            throw new Error(`[dependency-policy] ${message}`);
+        default:
+            return 'usePlugin';
+    }
+}
+function resolveProjectOhPackagePath(projectRoot, loaded, projectOhPackagePath) {
+    const configured = projectOhPackagePath ?? loaded.config.projectOhPackagePath;
+    if (!configured) {
+        return path_1.default.resolve(projectRoot, 'oh-package.json5');
+    }
+    return path_1.default.isAbsolute(configured)
+        ? configured
+        : path_1.default.resolve(projectRoot, configured);
+}

package/dist/path-utils.d.ts

@@ -0,0 +1,3 @@
+import type { ApplyEnvironment, PathBase } from './types';
+export declare function normalizeDependencyValueForProjectOhPackage(rawValue: string, env: ApplyEnvironment, rulePathBase?: PathBase): string;
+export declare function toPosix(value: string): string;

package/dist/path-utils.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeDependencyValueForProjectOhPackage = normalizeDependencyValueForProjectOhPackage;
+exports.toPosix = toPosix;
+const path_1 = __importDefault(require("path"));
+function normalizeDependencyValueForProjectOhPackage(rawValue, env, rulePathBase) {
+    if (!rawValue.startsWith('file:')) {
+        return rawValue;
+    }
+    const rawPath = rawValue.slice('file:'.length);
+    if (rawPath.length === 0) {
+        return rawValue;
+    }
+    const absolutePath = resolveFileDependencyPath(rawPath, env, rulePathBase);
+    const relativeToProject = toPosix(path_1.default.relative(env.projectRoot, absolutePath));
+    if (relativeToProject.length === 0) {
+        return 'file:.';
+    }
+    if (relativeToProject.startsWith('..')) {
+        return `file:${relativeToProject}`;
+    }
+    if (relativeToProject.startsWith('.')) {
+        return `file:${relativeToProject}`;
+    }
+    return `file:./${relativeToProject}`;
+}
+function resolveFileDependencyPath(rawPath, env, rulePathBase) {
+    const prefixed = resolveExplicitPrefix(rawPath, env);
+    if (prefixed) {
+        return prefixed;
+    }
+    if (path_1.default.isAbsolute(rawPath)) {
+        return path_1.default.resolve(rawPath);
+    }
+    const base = resolvePathBase(rulePathBase ?? env.pathBase, env);
+    return path_1.default.resolve(base, rawPath);
+}
+function resolveExplicitPrefix(rawPath, env) {
+    const candidates = [
+        ['$project/', env.projectRoot],
+        ['$config/', env.configDir],
+        ['$plugin/', env.pluginRoot]
+    ];
+    for (const [prefix, base] of candidates) {
+        if (rawPath.startsWith(prefix)) {
+            return path_1.default.resolve(base, rawPath.slice(prefix.length));
+        }
+    }
+    return undefined;
+}
+function resolvePathBase(base, env) {
+    switch (base) {
+        case 'projectRoot':
+            return env.projectRoot;
+        case 'configFile':
+            return env.configDir;
+        case 'pluginRoot':
+            return env.pluginRoot;
+        default:
+            return env.projectRoot;
+    }
+}
+function toPosix(value) {
+    return value.split(path_1.default.sep).join('/');
+}

package/dist/policy-loader.d.ts

@@ -0,0 +1,3 @@
+import type { DependencyPolicyConfig, DependencyPolicyPluginOptions, LoadedPolicyConfig } from './types';
+export declare function loadPolicyConfig(projectRoot: string, options: DependencyPolicyPluginOptions): LoadedPolicyConfig;
+export declare function resolveProfileName(config: DependencyPolicyConfig, options: DependencyPolicyPluginOptions): string;

package/dist/policy-loader.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPolicyConfig = loadPolicyConfig;
+exports.resolveProfileName = resolveProfileName;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const json5_1 = __importDefault(require("json5"));
+const VALID_CONFLICT_POLICIES = [
+    'pluginWins',
+    'projectWins',
+    'warn',
+    'error'
+];
+const VALID_PATH_BASES = [
+    'projectRoot',
+    'configFile',
+    'pluginRoot'
+];
+function loadPolicyConfig(projectRoot, options) {
+    const pluginRoot = path_1.default.resolve(__dirname, '..');
+    const configPath = options.configPath
+        ? resolveMaybeRelative(projectRoot, options.configPath)
+        : path_1.default.resolve(pluginRoot, 'config', 'dependency-policy.json5');
+    if (!fs_1.default.existsSync(configPath)) {
+        throw new Error(`[dependency-policy] config not found: ${configPath}`);
+    }
+    const content = fs_1.default.readFileSync(configPath, 'utf-8');
+    const config = json5_1.default.parse(content);
+    validatePolicyConfig(config, configPath);
+    return {
+        config,
+        configPath,
+        configDir: path_1.default.dirname(configPath),
+        pluginRoot
+    };
+}
+function resolveProfileName(config, options) {
+    const profileName = options.profile ?? process.env.DEP_POLICY_PROFILE ?? config.defaultProfile;
+    if (!profileName) {
+        throw new Error('[dependency-policy] profile is not specified. Pass dependencyPolicyPlugin({ profile }) or set DEP_POLICY_PROFILE.');
+    }
+    if (!config.profiles || !config.profiles[profileName]) {
+        throw new Error(`[dependency-policy] profile not found: ${profileName}`);
+    }
+    return profileName;
+}
+function validatePolicyConfig(config, configPath) {
+    if (!config || typeof config !== 'object') {
+        throw new Error(`[dependency-policy] invalid config: ${configPath}`);
+    }
+    if (config.schemaVersion !== 2) {
+        throw new Error(`[dependency-policy] unsupported schemaVersion: ${String(config.schemaVersion)}. Expected 2.`);
+    }
+    if (!config.profiles || typeof config.profiles !== 'object') {
+        throw new Error('[dependency-policy] config.profiles is required.');
+    }
+    if (config.conflictPolicy !== undefined &&
+        !VALID_CONFLICT_POLICIES.includes(config.conflictPolicy)) {
+        throw new Error(`[dependency-policy] invalid conflictPolicy: ${config.conflictPolicy}`);
+    }
+    if (config.pathBase !== undefined && !VALID_PATH_BASES.includes(config.pathBase)) {
+        throw new Error(`[dependency-policy] invalid pathBase: ${config.pathBase}`);
+    }
+    for (const [profileName, profile] of Object.entries(config.profiles)) {
+        if (!profile || typeof profile !== 'object') {
+            throw new Error(`[dependency-policy] invalid profile: ${profileName}`);
+        }
+        if (profile.app?.strategy !== undefined && !['merge', 'replace'].includes(profile.app.strategy)) {
+            throw new Error(`[dependency-policy] invalid app.strategy in profile ${profileName}: ${profile.app.strategy}`);
+        }
+    }
+}
+function resolveMaybeRelative(baseDir, value) {
+    return path_1.default.isAbsolute(value) ? value : path_1.default.resolve(baseDir, value);
+}

package/dist/project-root.d.ts

@@ -0,0 +1,3 @@
+import type { HvigorNode } from '@ohos/hvigor';
+export declare function resolveProjectRoot(currentNode: HvigorNode): string;
+export declare function safeCallString(target: unknown, methodName: string): string | undefined;

package/dist/project-root.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProjectRoot = resolveProjectRoot;
+exports.safeCallString = safeCallString;
+const path_1 = __importDefault(require("path"));
+function resolveProjectRoot(currentNode) {
+    const fromNodeDir = safeCallString(currentNode, 'getNodeDir');
+    if (fromNodeDir) {
+        return path_1.default.resolve(fromNodeDir);
+    }
+    const fromNodePath = safeCallString(currentNode, 'getNodePath');
+    if (fromNodePath) {
+        return path_1.default.resolve(fromNodePath);
+    }
+    return process.cwd();
+}
+function safeCallString(target, methodName) {
+    const maybeObject = target;
+    const method = maybeObject?.[methodName];
+    if (typeof method !== 'function') {
+        return undefined;
+    }
+    try {
+        const value = method.call(target);
+        return typeof value === 'string' && value.length > 0 ? value : undefined;
+    }
+    catch (_error) {
+        return undefined;
+    }
+}

package/dist/report.d.ts

@@ -0,0 +1,2 @@
+import type { OverridesReport } from './types';
+export declare function writeOverridesReport(projectRoot: string, report: OverridesReport): string;

package/dist/report.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeOverridesReport = writeOverridesReport;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function writeOverridesReport(projectRoot, report) {
+    const reportDir = path_1.default.resolve(projectRoot, 'build', 'dependency-policy');
+    const reportPath = path_1.default.resolve(reportDir, 'overrides-report.json');
+    fs_1.default.mkdirSync(reportDir, { recursive: true });
+    fs_1.default.writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf-8');
+    return reportPath;
+}

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+export type ConflictPolicy = 'pluginWins' | 'projectWins' | 'warn' | 'error';
+export type PathBase = 'projectRoot' | 'configFile' | 'pluginRoot';
+export type ApplyStrategy = 'merge' | 'replace';
+export interface DependencyMap {
+    [packageName: string]: string;
+}
+export interface DependencyPolicyPluginOptions {
+    /** Path relative to project root, or an absolute path. */
+    configPath?: string;
+    /** Explicit profile name. If omitted, DEP_POLICY_PROFILE or defaultProfile is used. */
+    profile?: string;
+    /** If true, compute and report changes but do not write oh-package.json5. */
+    dryRun?: boolean;
+    /** Override config.report. */
+    report?: boolean;
+    /** Console log level. */
+    logLevel?: LogLevel;
+    /** Project root oh-package file. Defaults to <projectRoot>/oh-package.json5. */
+    projectOhPackagePath?: string;
+    /** Create a one-time backup next to oh-package.json5 before writing. Defaults to false. */
+    backup?: boolean;
+}
+export interface DependencyPolicyConfig {
+    schemaVersion: 2;
+    defaultProfile?: string;
+    conflictPolicy?: ConflictPolicy;
+    pathBase?: PathBase;
+    report?: boolean;
+    projectOhPackagePath?: string;
+    profiles: Record<string, DependencyProfile>;
+}
+export interface DependencyProfile {
+    app?: AppRule;
+    /**
+     * v2 intentionally does not materialize module-level direct dependencies.
+     * Keep this field only so old configs produce a clear warning instead of failing parsing.
+     */
+    modules?: Record<string, unknown>;
+}
+export interface AppRule {
+    /** merge keeps existing overrides; replace rewrites the whole overrides object. */
+    strategy?: ApplyStrategy;
+    pathBase?: PathBase;
+    overrides?: DependencyMap;
+    remove?: {
+        overrides?: string[];
+    };
+}
+export interface LoadedPolicyConfig {
+    config: DependencyPolicyConfig;
+    configPath: string;
+    configDir: string;
+    pluginRoot: string;
+}
+export interface OverridesDiff {
+    before: DependencyMap;
+    after: DependencyMap;
+    added: DependencyMap;
+    changed: Record<string, {
+        from: string;
+        to: string;
+    }>;
+    removed: DependencyMap;
+    keptByProjectWins: Record<string, {
+        project: string;
+        plugin: string;
+    }>;
+}
+export interface OverridesReport {
+    pluginId: string;
+    schemaVersion: number;
+    profile: string;
+    dryRun: boolean;
+    projectRoot: string;
+    projectOhPackagePath: string;
+    configPath: string;
+    changed: boolean;
+    warnings: string[];
+    overrides: OverridesDiff;
+}
+export interface ApplyEnvironment {
+    projectRoot: string;
+    configDir: string;
+    pluginRoot: string;
+    pathBase: PathBase;
+    conflictPolicy: ConflictPolicy;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "hvigor-dependency-policy-plugin",
+  "version": "0.2.0-beta",
+  "publishConfig": {
+    "registry": "https://repo.harmonyos.com/npm/"
+  },
+  "description": "Apply dependency policy by materializing project-level oh-package.json5 overrides.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "config",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepack": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "json5": "^2.2.3"
+  },
+  "peerDependencies": {
+    "@ohos/hvigor": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@ohos/hvigor": ">=5.0.0",
+    "@types/node": "^20.11.30",
+    "typescript": "^5.4.5"
+  }
+}