mm_scanner 0.0.0-stage → 1.0.0

package/example/data/app/app.json

@@ -0,0 +1,5 @@
+{
+  "name": "demo_app",
+  "version": "1.0.0",
+  "description": "示例应用配置"
+}

package/example/data/config/db.json

@@ -0,0 +1,4 @@
+{
+  "host": "127.0.0.1",
+  "port": 3306
+}

package/example/data/config/logger.js

@@ -0,0 +1,3 @@
+module.exports = {
+  level: 'info'
+};

package/example/data/dist/build.json

@@ -0,0 +1,3 @@
+{
+  "name": "build_artifact"
+}

package/example/data/readme.txt

@@ -0,0 +1 @@
+演示文件，不会被默认配置扫描

package/example/demo.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const path = require('path');
+const { Scanner, scannerAdmin } = require('../index');
+
+/**
+ * 使用示例：扫描 example/data 目录并按多种方式检索文件
+ */
+function demo() {
+  const dir = path.join(__dirname, 'data');
+
+  // 1. 创建扫描器，默认只扫描 .json，并忽略 node_modules 与 .git
+  const scanner = new Scanner();
+  console.log('=== 默认配置 ===');
+  console.log('  扩展名: ' + scanner.extensions.join(', '));
+  console.log('  忽略目录: ' + scanner.config.ignore.join(', '));
+
+  // 2. 扫描目录，可重复调用（仅首次生效）
+  scanner.scan(dir);
+  console.log('=== 扫描结果 ===');
+  console.log('  基目录: ' + scanner.baseDir);
+  console.log('  文件数: ' + scanner.size);
+  for (const key of scanner.keys()) {
+    console.log('  ' + key);
+  }
+
+  // 3. 按 key 查询，key 可省略扩展名
+  console.log('=== 按 key 查询 ===');
+  console.log('  元信息: ' + JSON.stringify(scanner.get('app/app')));
+  console.log('  绝对路径: ' + scanner.getPath('config/db'));
+  console.log('  是否存在 config/logger: ' + scanner.has('config/logger'));
+
+  // 4. 按扩展名、目录、层级筛选
+  console.log('=== 分类检索 ===');
+  console.log('  .json 文件: ' + scanner.getByExt('.json').length + ' 个');
+  console.log('  config 目录: ' + scanner.getByDir('config').map((f) => f.key).join(', '));
+  console.log('  一级子目录: ' + scanner.dirTypes().join(', '));
+  console.log('  扩展名类型: ' + scanner.extTypes().join(', '));
+
+  // 5. 自定义扩展名与忽略目录
+  const custom = new Scanner({ extensions: ['json', 'js'], ignore: ['dist'] });
+  custom.scan(dir);
+  console.log('=== 自定义配置 ===');
+  console.log('  文件数: ' + custom.size);
+  console.log('  文件列表: ' + custom.keys().join(', '));
+  console.log('  dist 目录已被忽略: ' + (custom.getByDir('dist').length === 0));
+
+  // 6. 文件变化后重新扫描
+  custom.rescan();
+  console.log('=== 重新扫描 ===');
+  console.log('  文件数: ' + custom.size);
+
+  // 7. 通过 admin 按作用域复用扫描器实例
+  const os_scanner = scannerAdmin('os', { extensions: ['json'] });
+  const demo_scanner = scannerAdmin('demo');
+  console.log('=== 作用域实例 ===');
+  console.log('  os 实例类型正确: ' + (os_scanner instanceof Scanner));
+  console.log('  重复获取 os 实例复用缓存: ' + (scannerAdmin('os') === os_scanner));
+  console.log('  demo 实例与 os 实例相互独立: ' + (demo_scanner !== os_scanner));
+}
+
+demo();

package/index.js

@@ -0,0 +1,16 @@
+const Scanner = require('./lib/scanner');
+const Admin = require('mm_corejs').Admin;
+
+const admin = new Admin();
+admin.setClass(Scanner);
+
+module.exports = {
+  Scanner,
+  admin,
+  scannerAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, config);
+  }
+};

package/lib/scanner.js

@@ -0,0 +1,264 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/* key 规范化：只统一分隔符、去首尾 /，不再剥扩展名 */
+function normalizeKey(p) {
+  return String(p)
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/^\/+|\/+$/g, '');
+}
+
+/* 扩展名规范化：补点、转小写 */
+function normalizeExt(ext) {
+  const e = String(ext).trim().toLowerCase();
+  return e.startsWith('.') ? e : '.' + e;
+}
+
+/**
+ * 合并默认配置与用户配置
+ * @param {{ extensions: string[], ignore: string[] }} default_config - 默认配置
+ * @param {{ extensions?: string[], ignore?: string[] }} config - 用户配置
+ * @returns {{ extensions: string[], ignore: string[] }} 规范化后的配置
+ */
+function createConfig(default_config, config) {
+  const extensions =
+    Array.isArray(config.extensions) && config.extensions.length
+      ? config.extensions
+      : default_config.extensions;
+  const ignore = Array.isArray(config.ignore) ? config.ignore : default_config.ignore;
+
+  return {
+    extensions: extensions.map(normalizeExt),
+    ignore: [...ignore],
+  };
+}
+
+class Scanner {
+  /**
+   * 扫描器默认配置
+   */
+  static config = {
+    /** 支持的扩展名 */
+    extensions: ['.json'],
+    /** 忽略的目录 */
+    ignore: ['node_modules', '.git'],
+  };
+
+  /** key(含扩展名) -> { key, absPath, relPath, dir, name, ext } */
+  #files = new Map();
+  #baseDir = null;
+  #scanned = false;
+
+  /**
+   * 创建扫描器实例
+   * @param {{ extensions?: string[], ignore?: string[] }} [config] - 扫描器配置
+   */
+  constructor(config = {}) {
+    this.config = createConfig(Scanner.config, config);
+  }
+
+  /* -------- 私有 -------- */
+
+  #walk(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (this.config.ignore.includes(entry.name)) continue;
+        this.#walk(fullPath);
+        continue;
+      }
+
+      if (!entry.isFile()) continue;
+
+      const ext = path.extname(entry.name).toLowerCase();
+      if (!this.config.extensions.includes(ext)) continue;
+
+      const relPath = path.relative(this.#baseDir, fullPath).replace(/\\/g, '/');
+      const key = normalizeKey(relPath);              // 保留扩展名，如 'config/app.json'
+      const dirPart = path.posix.dirname(relPath);
+
+      this.#files.set(key, {
+        key,
+        absPath: fullPath,
+        relPath,
+        dir: dirPart === '.' ? '' : dirPart,
+        name: path.basename(relPath, ext),
+        ext,
+      });
+    }
+  }
+
+  #ensureReady() {
+    if (!this.#scanned) {
+      throw new Error('[scanner] 尚未初始化，请先在入口调用 scanner.scan(dir)');
+    }
+  }
+
+  /** 宽松解析 key：精确命中 → 按扩展名顺序尝试补全 */
+  #resolveKey(input) {
+    const norm = normalizeKey(input);
+    if (this.#files.has(norm)) return norm;
+
+    for (const ext of this.config.extensions) {
+      const tryKey = norm + ext;
+      if (this.#files.has(tryKey)) return tryKey;
+    }
+    return null;
+  }
+
+  /**
+   * 判断文件的相对目录是否命中目标目录
+   * @param {string} dir_path - 文件所在相对目录
+   * @param {string} dir_key - 规范化后的目标目录
+   * @returns {boolean} 命中返回 true，目标目录为空时视为全部命中
+   */
+  #matchDir(dir_path, dir_key) {
+    if (!dir_key) return true;
+    if (dir_key.includes('/')) {
+      return dir_path === dir_key || dir_path.endsWith('/' + dir_key);
+    }
+    return dir_path.split('/').includes(dir_key);
+  }
+
+  /* -------- 公开 API -------- */
+
+  /**
+   * 扫描目录（重复调用只生效一次）
+   * @param {string} dir
+   * @param {{ extensions?: string[], ignore?: string[] }} [options]
+   */
+  scan = (dir, options = {}) => {
+    const resolved = path.resolve(dir);
+
+    if (this.#scanned) {
+      if (this.#baseDir !== resolved) {
+        console.warn(`[scanner] 已使用 ${this.#baseDir} 扫描过，忽略本次 scan(${resolved})`);
+      }
+      return this;
+    }
+
+    if (!fs.existsSync(resolved)) throw new Error(`[scanner] 目录不存在: ${resolved}`);
+    if (!fs.statSync(resolved).isDirectory()) throw new Error(`[scanner] 不是目录: ${resolved}`);
+
+    if (Array.isArray(options.extensions) || Array.isArray(options.ignore)) {
+      this.config = createConfig(this.config, options);
+    }
+
+    this.#baseDir = resolved;
+    this.#walk(resolved);
+    this.#scanned = true;
+    return this;
+  };
+
+  /** 拿条目元信息（含 absPath），key 可带可不带扩展名 */
+  get = (key) => {
+    this.#ensureReady();
+    const k = this.#resolveKey(key);
+    return k ? this.#files.get(k) : undefined;
+  };
+
+  /** 拿绝对路径（给 Loader 用的最常见接口） */
+  getPath = (key) => {
+    const info = this.get(key);
+    return info ? info.absPath : undefined;
+  };
+
+  has = (key) => {
+    this.#ensureReady();
+    return this.#resolveKey(key) !== null;
+  };
+
+  keys = () => {
+    this.#ensureReady();
+    return [...this.#files.keys()];
+  };
+
+  getAll = () => {
+    this.#ensureReady();
+    return [...this.#files.values()];
+  };
+
+  /** 按"扩展名类型"筛：getByExt('.json') / getByExt('json') 都行 */
+  getByExt = (ext) => {
+    this.#ensureReady();
+    const e = normalizeExt(ext);
+    return this.getAll().filter((f) => f.ext === e);
+  };
+
+  /** 所有出现过的扩展名类型 */
+  extTypes = () => {
+    this.#ensureReady();
+    const set = new Set();
+    for (const f of this.#files.values()) set.add(f.ext);
+    return [...set];
+  };
+
+  /** 按目录筛：getByDir('config') -> data/config/**.{json,yaml,...} */
+  getByDir = (dir) => {
+    this.#ensureReady();
+    const norm = normalizeKey(dir);
+    const prefix = norm ? norm + '/' : '';
+    return this.getAll().filter((f) => f.key.startsWith(prefix));
+  };
+
+  /**
+   * 判断文件是否命中指定类型
+   * 只写扩展名（'.json' / 'json'）按扩展名匹配，写文件名（'event.json'）按文件名结尾匹配
+   * @param {{ key: string, ext: string }} file - 文件条目
+   * @param {string} ext - 扩展名或文件名
+   * @returns {boolean} 命中返回 true
+   */
+  #matchExt(file, ext) {
+    const norm = String(ext).trim().toLowerCase();
+    const bare = norm.replace(/^\./, '');
+    if (!bare.includes('.')) return file.ext === '.' + bare;
+    return file.key === bare || file.key.endsWith('/' + bare);
+  }
+
+  /**
+   * 按目录名与文件类型筛选文件
+   * 目录参数可为目录名（匹配任意层级）或相对路径（匹配路径结尾）
+   * @param {string} dir - 目录名或相对目录，如 'event_api'、'ai/event_api'
+   * @param {string} ext - 扩展名或文件名，如 '.json'、'event.json'
+   * @returns {Array<{ key: string, absPath: string, relPath: string, dir: string, name: string, ext: string }>} 命中的文件条目
+   */
+  getFileByDir = (dir, ext) => {
+    this.#ensureReady();
+    const dir_key = normalizeKey(dir);
+    return this.getAll().filter((f) => this.#matchDir(f.dir, dir_key) && this.#matchExt(f, ext));
+  };
+
+  /** 所有一级子目录名（可当作业务分类） */
+  dirTypes = () => {
+    this.#ensureReady();
+    const set = new Set();
+    for (const f of this.#files.values()) {
+      const first = f.dir.split('/')[0];
+      if (first) set.add(first);
+    }
+    return [...set];
+  };
+
+  /** 当前支持的扩展名列表 */
+  get extensions() { return [...this.config.extensions]; }
+
+  /** 重新扫描（开发环境热更新用） */
+  rescan = () => {
+    if (!this.#baseDir) throw new Error('[scanner] 尚未初始化，无法 rescan');
+    this.#files.clear();
+    this.#walk(this.#baseDir);
+    return this;
+  };
+
+  get size() { return this.#files.size; }
+  get baseDir() { return this.#baseDir; }
+}
+
+/* 导出单例 + 类 */
+module.exports = Scanner;

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "mm_scanner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "目录扫描器，按扩展名递归扫描目录并缓存文件元信息，支持按 key、扩展名、目录检索文件路径。",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_scanner.git"
+  },
+  "keywords": [
+    "mm_mod",
+    "mm_infra",
+    "mm_common",
+    "超级美眉",
+    "目录扫描",
+    "文件检索",
+    "scanner"
+  ],
+  "layer": "infra",
+  "group": "common",
+  "author": "邱文武",
+  "license": "ISC",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib",
+    "example"
+  ],
+  "directories": {
+    "example": "example",
+    "lib": "lib"
+  },
+  "scripts": {
+    "test": "jest --coverage",
+    "demo": "node example/demo.js",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "mm_corejs": "^1.1.5"
+  },
+  "devDependencies": {
+    "jest": "^30.5.2"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.