@yalehwang/cloudpit 2.0.0 → 3.0.0

package/scripts/brand-allowlist-check.mjs

@@ -18,6 +18,19 @@
  * value-by-value so changing a display string can never touch a translation KEY (the locale
  * key-set digest pins every key).
  *
+ * The `brand-lines` kind is the code-wide sweep instrument: it matches ONLY the uppercase
+ * product token `CloudCLI`, on EVERY line including comments, and it expands directory globs
+ * (`server/**`, `src/**`, ...) over text extensions only — never `.json`, `.md` or binaries.
+ * Directory expansion never descends into `node_modules` or `.git`: installed packages and
+ * build caches (the e2e bundle cache under `server/node_modules/.cache`) are generated
+ * artifacts, not surfaces a sweep can or should fix, and walking them made the reading depend
+ * on which caches happened to exist in the checkout.
+ * That is deliberately narrower and wider at once than `code`: narrower in tokens (`claudecodeui`
+ * and `@yalehwang/cloudcli` keep their existing `code`-surface treatment), wider in lines (a
+ * stale comment in shipped source is still part of the brand surface). Its allowlist spans are
+ * FILE-SCOPED, so the legacy install directory literal is permitted only in the two migration
+ * modules and their tests, never as a global rule that would also swallow product copy.
+ *
  * The deprecated package name is matched in its lowercase spelling only (`@yalehwang/cloudcli`):
  * the product-visible token is `CloudCLI`, while the update path is the package name the CLI and
  * `system.service.ts` feed to npm. History-only files (CHANGELOG / `release.yml` comments /
@@ -42,9 +55,16 @@ import { fileURLToPath } from 'node:url';
  * `json-values`   — parsed JSON string values only (keys are not user-visible copy).
  * `locale-values` — same as `json-values`, but counted as locale copy in the readings.
  * `readme-install`— only install/upgrade command lines, so upstream attribution prose is skipped.
+ * `doc-head`      — a current document's brand-bearing head: H1 headings, logo `alt` text, and
+ *                   install/upgrade command lines. Body prose is skipped so upstream-product
+ *                   references kept for attribution do not need an allowlist span.
  * `code`          — every line except comment lines.
+ * `brand-lines`   — every line, comments included, matched against `CloudCLI` only. A surface
+ *                   of this kind may name a directory glob (`server/**` or `server/**\/*.ts`);
+ *                   it expands over text extensions, skips the checker's own files, and never
+ *                   descends into `node_modules` or `.git`.
  *
- * @typedef {'text' | 'json-values' | 'locale-values' | 'readme-install' | 'code'} SurfaceKind
+ * @typedef {'text' | 'json-values' | 'locale-values' | 'readme-install' | 'doc-head' | 'code' | 'brand-lines'} SurfaceKind
  */
 
 /**
@@ -56,9 +76,10 @@ import { fileURLToPath } from 'node:url';
 
 /**
  * One piece of brand-bearing text extracted from a surface. `label` is the line number for
- * line-oriented surfaces and the JSON path for value-oriented ones.
+ * line-oriented surfaces and the JSON path for value-oriented ones. `brandLines` marks a source
+ * from a `brand-lines` surface, which matches `CloudCLI` alone instead of the full token set.
  *
- * @typedef {{ file: string, label: string, text: string }} BrandSource
+ * @typedef {{ file: string, label: string, text: string, brandLines?: boolean }} BrandSource
  */
 
 /**
@@ -82,6 +103,9 @@ import { fileURLToPath } from 'node:url';
  *   scannedSources: number,
  *   localeValues: number,
  *   allowlistHits: number,
+ *   docSurfaces: number,
+ *   docSurfaceFiles: string[],
+ *   brandLineFiles: number,
  * }} CheckReadings
  * @typedef {{
  *   exitCode: number,
@@ -91,6 +115,35 @@ import { fileURLToPath } from 'node:url';
  * }} CheckResult
  */
 
+/**
+ * Current documentation surfaces: the docs a reader lands on today. This list is deliberately
+ * explicit (no `docs/**` glob) so the historical surface — `docs/proposals/`, `docs/experiments/`,
+ * `adr/`, `CHANGELOG.md`, `NOTICE`, `LICENSE` — stays out of the scan. Those files record the past
+ * and are not rewritten by a brand sweep.
+ *
+ * README and the translated READMEs use `doc-head` (H1 / logo alt / install block) rather than
+ * `text`: their bodies intentionally keep upstream attribution (`CloudCLI UI`, `CloudCLI Cloud`)
+ * that the allowlist must not be widened to swallow.
+ *
+ * @type {ScannedSurface[]}
+ */
+export const CURRENT_DOC_SURFACES = [
+  { glob: 'README.md', kind: 'doc-head' },
+  { glob: 'CONTRIBUTING.md', kind: 'text' },
+  { glob: 'docs/README.de.md', kind: 'doc-head' },
+  { glob: 'docs/README.ja.md', kind: 'doc-head' },
+  { glob: 'docs/README.ko.md', kind: 'doc-head' },
+  { glob: 'docs/README.ru.md', kind: 'doc-head' },
+  { glob: 'docs/README.tr.md', kind: 'doc-head' },
+  { glob: 'docs/README.zh-CN.md', kind: 'doc-head' },
+  { glob: 'docs/README.zh-TW.md', kind: 'doc-head' },
+  { glob: 'docs/architecture/cockpit-attention/01-planes.puml', kind: 'text' },
+  { glob: 'docs/architecture/cockpit-attention/CARD-PROVIDERS.md', kind: 'text' },
+  { glob: 'docs/architecture/cockpit-attention/INTERACTION-PRINCIPLES.md', kind: 'text' },
+  { glob: 'docs/architecture/cockpit-attention/README.md', kind: 'text' },
+  { glob: 'docs/architecture/knowledge-application/FACT-CONTRACT.md', kind: 'text' },
+];
+
 /**
  * Every user-visible surface AC-451 owns. Keep this list aligned with the Proposal's
  * scan-surface section: the criterion asserts the list covers each named file/glob.
@@ -101,9 +154,16 @@ import { fileURLToPath } from 'node:url';
  * @type {ScannedSurface[]}
  */
 export const SCANNED_SURFACES = [
+  ...CURRENT_DOC_SURFACES,
+  // Code-wide sweep surfaces. These expand over text extensions only (see TEXT_EXTENSIONS),
+  // scan comments too, and match only the uppercase `CloudCLI` token.
+  { glob: 'server/**', kind: 'brand-lines' },
+  { glob: 'src/**', kind: 'brand-lines' },
+  { glob: 'electron/**', kind: 'brand-lines' },
+  { glob: 'scripts/**', kind: 'brand-lines' },
+  { glob: 'public/**', kind: 'brand-lines' },
   { glob: 'index.html', kind: 'text' },
   { glob: 'public/manifest.json', kind: 'json-values' },
-  { glob: 'README.md', kind: 'readme-install' },
   { glob: 'src/modules/i18n/locales/**/*.json', kind: 'locale-values' },
   { glob: 'src/shared/utils.ts', kind: 'code' },
   { glob: 'src/modules/chat-session/utils/session/pageTitleNotification.ts', kind: 'code' },
@@ -132,7 +192,12 @@ export const SCANNED_SURFACES = [
  * these matches. Spans (not whole lines) keep a line that mixes allowed and disallowed copy from
  * passing: `CloudCLI Cloud and CloudCLI` still reports the second token.
  *
- * @type {{ name: string, pattern: RegExp }[]}
+ * `files` scopes a span to a set of repo-relative paths / `dir/**` prefixes. An entry without
+ * `files` applies to every surface, which is what the upstream-attribution spans need. The
+ * legacy-install spans are scoped because the only legitimate `CloudCLI` left in shipped code
+ * names an OLD on-disk directory or Windows shortcut, not the product.
+ *
+ * @type {{ name: string, pattern: RegExp, files?: string[] }[]}
  */
 export const BRAND_ALLOWLIST = [
   // Third-party / external services that keep their own name.
@@ -155,6 +220,9 @@ export const BRAND_ALLOWLIST = [
   },
   // The unrenamed local cache directory (`~/.cache/claudecodeui`), a filesystem name, not copy.
   { name: 'local-cache-directory', pattern: /['"]\.cache['"]\s*,\s*['"]claudecodeui['"]/g },
+  // The knowledge-application fact contract's `identity.project` is a wire value consumers read,
+  // naming the repository, not the product. It stays `claudecodeui` by contract.
+  { name: 'knowledge-application-project-id', pattern: /"project"\s*:\s*"claudecodeui"/g },
   // The deprecated package name is history, not an update path. These spans cover the three
   // historical reference shapes (migration notice, release-workflow comment, changelog entry);
   // `npm show|update|install -g @yalehwang/cloudcli` matches none of them and stays a violation.
@@ -164,16 +232,103 @@ export const BRAND_ALLOWLIST = [
     pattern: /(?:publishes the package to npm as|the) `@yalehwang\/cloudcli`/g,
   },
   { name: 'legacy-package-changelog-entry', pattern: /publish the fork as @yalehwang\/cloudcli on npm/g },
+  // The OLD desktop installation name. `userDataMigration.js` and `appIdMigration.js` read it to
+  // move an existing install; their tests pin the literal. File-scoped so no other file can use
+  // `CloudCLI` as copy. The tests' broad allowance covers the directory, shortcut and .desktop
+  // shapes without enumerating each one.
+  {
+    name: 'legacy-install-name',
+    pattern: /CloudCLI/g,
+    files: [
+      'electron/userDataMigration.js',
+      'electron/appIdMigration.js',
+      'electron/tests/**',
+    ],
+  },
+  // Two comments that describe the legacy install rather than the product: the old userData
+  // folder read by main.js and the old local-server path localServer.js still keeps readable.
+  { name: 'legacy-install-comment', pattern: /legacy CloudCLI folder/g, files: ['electron/main.js'] },
+  {
+    name: 'legacy-install-comment',
+    pattern: /the CloudCLI path stays readable/g,
+    files: ['electron/localServer.js'],
+  },
+  // The distribution checker asserts the README/NOTICE attribution string; it is upstream copy,
+  // not a product title.
+  {
+    name: 'upstream-ui-attribution',
+    pattern: /CloudCLI UI/g,
+    files: ['scripts/cloudpit-distribution-check.mjs'],
+  },
+  // Third-party plugin repository URL and its i18n key: the upstream project is called
+  // `CloudCLI-GLM-Usage`, and the key spelling is part of the locale contract.
+  {
+    name: 'third-party-plugin-repository',
+    pattern: /CloudCLI-GLM-Usage/g,
+    files: ['src/modules/plugins/PluginSettingsTab.tsx'],
+  },
+  {
+    name: 'third-party-plugin-i18n-key',
+    pattern: /prismCloudCLI/g,
+    files: ['src/modules/plugins/PluginSettingsTab.tsx'],
+  },
 ];
 
 const BRAND_TOKEN = /CloudCLI|claudecodeui|@yalehwang\/cloudcli/g;
 
+/** The only token a `brand-lines` surface matches. */
+const BRAND_LINE_TOKEN = /CloudCLI/g;
+
+/**
+ * Extensions a `brand-lines` directory glob expands over. Data (`.json`), prose (`.md`) and
+ * binaries are deliberately absent: the frozen ratchet baseline and historical records keep
+ * their old text, and a locale bundle is already covered value-by-value by its own surface.
+ */
+const TEXT_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs', '.sh', '.html']);
+
+/**
+ * Directory names a glob expansion never descends into. `node_modules` holds installed packages
+ * and generated build caches — including the e2e bundle cache this checker was red on — and
+ * `.git` holds repository internals. Neither carries shipped source, and walking them made the
+ * reading depend on which caches a checkout happened to contain (the main checkout had three
+ * stale bundles that a fresh task worktree did not).
+ */
+const EXCLUDED_DIRECTORIES = new Set(['node_modules', '.git']);
+
+/**
+ * The checker and its criterion are the scanning instrument and its negative control. Their
+ * prose necessarily names `CloudCLI`; excluding the pair keeps the instrument from scanning
+ * itself (the Proposal's whitelist item 3).
+ */
+const BRAND_LINE_EXCLUDED_FILES = new Set([
+  'scripts/brand-allowlist-check.mjs',
+  'scripts/brand-allowlist-check.test.mjs',
+]);
+
 /** A code line is documentation when its trimmed form opens a line/block/HTML comment. */
 const COMMENT_LINE = /^(?:\/\/|\/\*|\*|<!--)/;
 
 /** A README line that tells a user how to install or upgrade the package. */
 const README_INSTALL_LINE = /\bnpx\s+@yalehwang\/|\bnpm\s+(?:install|update)\s+-g\b/;
 
+/**
+ * A current-document line that carries the product identity: an HTML or markdown H1, a logo
+ * `<img>` carrying `alt` text, or an install/upgrade command. Everything else in those documents
+ * is prose whose upstream attribution is intentional.
+ *
+ * @param {string} line
+ * @returns {boolean}
+ */
+function isDocHeadLine(line) {
+  const trimmed = line.trim();
+  return (
+    /<h1\b/i.test(trimmed)
+    || /^#\s+/.test(trimmed)
+    || (/<img\b/i.test(trimmed) && /\balt=/i.test(trimmed))
+    || README_INSTALL_LINE.test(line)
+  );
+}
+
 /**
  * @param {string} dir
  * @returns {string[]} absolute file paths under `dir`
@@ -182,6 +337,9 @@ function listFilesRecursive(dir) {
   /** @type {string[]} */
   const files = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory() && EXCLUDED_DIRECTORIES.has(entry.name)) {
+      continue;
+    }
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...listFilesRecursive(full));
@@ -203,8 +361,30 @@ function expandSurface(root, surface) {
     return [surface.glob];
   }
   const dir = path.join(root, surface.glob.slice(0, wildcardIndex));
+  // A glob may carry an extension filter after the wildcard (`server/**/*.ts`); otherwise the
+  // surface kind decides (`brand-lines` uses every text extension, the rest stay JSON-only).
+  const suffix = surface.glob.slice(wildcardIndex + 3);
+  const extensionMatch = /^\/(?:\*\*\/)?\*(\.[A-Za-z0-9.]+)$/.exec(suffix);
+  const extension = extensionMatch ? extensionMatch[1].toLowerCase() : null;
   return listFilesRecursive(dir)
-    .filter((file) => file.endsWith('.json'))
+    .filter((file) => {
+      if (surface.kind === 'brand-lines') {
+        const relative = path.relative(root, file).split(path.sep).join('/');
+        if (BRAND_LINE_EXCLUDED_FILES.has(relative)) {
+          return false;
+        }
+        // Defense in depth: a glob whose own root sits under `node_modules`/`.git` never
+        // descends (listFilesRecursive already skips those directories), but a file path that
+        // still carries such a segment must not enter the sweep either.
+        if (relative.split('/').some((segment) => EXCLUDED_DIRECTORIES.has(segment))) {
+          return false;
+        }
+        return extension === null
+          ? TEXT_EXTENSIONS.has(path.extname(file).toLowerCase())
+          : file.endsWith(extension);
+      }
+      return file.endsWith('.json');
+    })
     .map((file) => path.relative(root, file).split(path.sep).join('/'))
     .sort();
 }
@@ -252,10 +432,18 @@ function extractSources(file, kind, content) {
     if (kind === 'readme-install' && !README_INSTALL_LINE.test(line)) {
       continue;
     }
+    if (kind === 'doc-head' && !isDocHeadLine(line)) {
+      continue;
+    }
     if (kind === 'code' && COMMENT_LINE.test(line.trim())) {
       continue;
     }
-    sources.push({ file, label: `${file}:${index + 1}`, text: line });
+    sources.push({
+      file,
+      label: `${file}:${index + 1}`,
+      text: line,
+      ...(kind === 'brand-lines' ? { brandLines: true } : {}),
+    });
   }
   return sources;
 }
@@ -272,13 +460,14 @@ export function scanSources(sources) {
   let allowlistHits = 0;
 
   for (const source of sources) {
-    const tokenPattern = new RegExp(BRAND_TOKEN.source, BRAND_TOKEN.flags);
+    const declaredToken = source.brandLines ? BRAND_LINE_TOKEN : BRAND_TOKEN;
+    const tokenPattern = new RegExp(declaredToken.source, declaredToken.flags);
     let match;
     while ((match = tokenPattern.exec(source.text)) !== null) {
       const token = match[0];
       const start = match.index;
       const end = start + token.length;
-      const allowlistEntry = findAllowlistSpan(source.text, start, end);
+      const allowlistEntry = findAllowlistSpan(source.text, start, end, source.file);
       if (allowlistEntry !== null) {
         allowlistHits += 1;
         continue;
@@ -308,15 +497,20 @@ export function findBrandViolations(sources) {
 }
 
 /**
- * The allowlist entry whose span contains `[start, end)`, or null.
+ * The allowlist entry whose span contains `[start, end)` and whose file scope admits `file`,
+ * or null.
  *
  * @param {string} text
  * @param {number} start
  * @param {number} end
+ * @param {string} file
  * @returns {string | null}
  */
-function findAllowlistSpan(text, start, end) {
+function findAllowlistSpan(text, start, end, file) {
   for (const entry of BRAND_ALLOWLIST) {
+    if (entry.files && !entry.files.some((pattern) => fileMatches(pattern, file))) {
+      continue;
+    }
     const pattern = new RegExp(entry.pattern.source, entry.pattern.flags);
     let match;
     while ((match = pattern.exec(text)) !== null) {
@@ -331,6 +525,22 @@ function findAllowlistSpan(text, start, end) {
   return null;
 }
 
+/**
+ * Whether a repo-relative path is admitted by an allowlist file scope. The only wildcard shape
+ * is a trailing `/**`, matching the directory itself and everything under it.
+ *
+ * @param {string} pattern
+ * @param {string} file
+ * @returns {boolean}
+ */
+function fileMatches(pattern, file) {
+  if (pattern.endsWith('/**')) {
+    const dir = pattern.slice(0, -3);
+    return file === dir || file.startsWith(`${dir}/`);
+  }
+  return file === pattern;
+}
+
 /**
  * Resolve every scanned surface into the text the token matcher reads.
  *
@@ -448,6 +658,9 @@ export function runBrandAllowlistCheck({ root, overrides = {} } = {}) {
   const resolvedRoot = path.resolve(root ?? process.cwd());
   const sources = collectBrandSources({ root: resolvedRoot, overrides });
   const scan = scanSources(sources);
+  const docSurfaceFiles = [
+    ...new Set(CURRENT_DOC_SURFACES.flatMap((surface) => expandSurface(resolvedRoot, surface))),
+  ].sort();
   /** @type {Record<string, any>} */
   const packageJson = JSON.parse(readFileSync(path.join(resolvedRoot, 'package.json'), 'utf8'));
   const identityViolations = checkDistributionIdentity(packageJson);
@@ -470,6 +683,13 @@ export function runBrandAllowlistCheck({ root, overrides = {} } = {}) {
       scannedSources: sources.length,
       localeValues: sources.filter((source) => source.file.startsWith('src/modules/i18n/locales/')).length,
       allowlistHits: scan.allowlistHits,
+      docSurfaces: docSurfaceFiles.length,
+      docSurfaceFiles,
+      // How many source files the code-wide `CloudCLI` sweep actually covered. A directory glob
+      // that silently expanded to nothing would otherwise look like a green sweep.
+      brandLineFiles: new Set(
+        sources.filter((source) => source.brandLines).map((source) => source.file),
+      ).size,
     },
     sources,
   };
@@ -505,7 +725,8 @@ export function main(argv = process.argv.slice(2)) {
     console.log(
       `brand-allowlist: files=${result.readings.scannedFiles} `
       + `values=${result.readings.scannedSources} localeValues=${result.readings.localeValues} `
-      + `allowlistHits=${result.readings.allowlistHits} violations=${result.violations.length}`,
+      + `allowlistHits=${result.readings.allowlistHits} docSurfaces=${result.readings.docSurfaces} `
+      + `brandLineFiles=${result.readings.brandLineFiles} violations=${result.violations.length}`,
     );
     for (const violation of result.violations) {
       console.error(`[brand] ${violation.message}`);