@jackwener/opencli 1.7.11 → 1.7.12

package/scripts/check-listing-id-pairing.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * check-listing-id-pairing.mjs — advisory report on listing↔detail id round-tripping.
+ *
+ * Soft convention (NOT a CI gate): when a site exposes both a listing-class
+ * command (search / hot / recent / trending / top / feed / popular / new /
+ * list) AND a detail-class command (read / article / paper / post / detail /
+ * view / job / page / book / movie / show / chapter / question / answer /
+ * tweet / video / track), it's usually nicer for agents if every listing row
+ * carries an id-shaped column whose value round-trips into the detail
+ * command. Without that, the agent has to re-search by title or scrape a URL
+ * to follow up.
+ *
+ * Why advisory and not a gate: whether a listing should pair with a detail
+ * is a case-by-case product/UX call (topic-string trending, profile-attribute
+ * key/value rows, UI-only sessions etc. legitimately don't pair). Forcing
+ * authors through an exempt list every PR was higher cognitive cost than the
+ * silent-loss bugs the rule actually catches. See PR #1311 thread for the
+ * "anti-pattern vs case-by-case" filter.
+ *
+ * What this script does:
+ *  1. Group cli-manifest.json entries by site.
+ *  2. For each site that has both classes, walk every listing entry and
+ *     check `columns` for at least one id-shaped name.
+ *  3. Print a report. Always exits 0 — never fails CI.
+ *
+ * Usage:
+ *   node scripts/check-listing-id-pairing.mjs   # print advisory report
+ *   npm run advise:listing-id-pairing
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MANIFEST = resolve(__dirname, '..', 'cli-manifest.json');
+
+/**
+ * Listing-class commands. Each row represents a single fetchable entity
+ * (post / paper / job / ...). The id of that entity must round-trip into
+ * the site's detail command.
+ */
+const LISTING_NAMES = new Set([
+    'search', 'hot', 'recent', 'trending', 'top', 'feed', 'popular',
+    'list', 'best', 'newest', 'latest', 'rising', 'controversial',
+    'home', 'timeline', 'browse', 'discover', 'jobs',
+    'unanswered', 'bounties', 'tag', 'user', 'venue',
+    'category', 'subreddit', 'question',
+]);
+
+/**
+ * Listing-class commands whose rows are sub-resources within a parent
+ * thread/session, NOT independently fetchable. Excluded from the rule:
+ *
+ * - `comments` / `replies` / `reviews` / `answer-list` / `thread-list`
+ *   — rows are comments under a parent post; the detail command fetches
+ *   the parent, not the comment
+ * - `ask` / `new` / `show` for AI-chat / agent-session sites — rows are
+ *   conversation turns within one session, not separately addressable
+ *
+ * These are intentionally NOT in `LISTING_NAMES` so the rule doesn't
+ * fire on them.
+ */
+
+
+const DETAIL_NAMES = new Set([
+    'read', 'article', 'paper', 'post', 'detail', 'view', 'job',
+    'page', 'book', 'movie', 'show-detail', 'chapter', 'tweet',
+    'video', 'track', 'note', 'review', 'item', 'product', 'episode',
+    'thread', 'comment-detail', 'profile-detail', 'shop',
+]);
+
+/** Columns whose name implies "this is an id you can pass to detail". */
+const ID_COLUMN_PATTERNS = [
+    /^id$/i,
+    /_id$/i,
+    /Id$/,
+    /^short_id$/i,
+    /^jk$/i,             // indeed
+    /^tid$/i,            // hupu / thread id
+    /^bvid$/i,           // bilibili
+    /^aid$/i,            // anime / bilibili av
+    /^asin$/i,           // amazon
+    /^sku$/i,            // jd / retail product SKU
+    /^isbn$/i,           // book sites
+    /^doi$/i,            // arxiv / openreview
+    /^slug$/i,           // dev.to / lobsters short slug
+    /^hn_id$/i,
+    /^username$/i,       // user-keyed detail (profile commands)
+    /^handle$/i,
+    /^uri$/i,            // bluesky AT URI (at://did:.../...)
+];
+
+function isUrlDetailCommand(entry) {
+    const args = Array.isArray(entry.args) ? entry.args : [];
+    const primaryArg = args.find((arg) => arg?.positional || arg?.required) ?? args[0];
+    if (!primaryArg) return false;
+    const name = String(primaryArg.name ?? '').toLowerCase();
+    if (name === 'url' || name === 'url-or-id') return true;
+
+    const help = String(primaryArg.help ?? '').toLowerCase();
+    if (!help) return false;
+
+    // Accept only explicit "this argument may be a URL" wording. Phrases
+    // like "id from URL" mean callers must extract an id before invoking
+    // the detail command, so listing.url must not satisfy the id-pair gate.
+    return (
+        /^full\b[^()]*\burl\b/.test(help) ||
+        /\burl\s+or\s+[^()]*\bid\b/.test(help) ||
+        /\bor\s+(?:a\s+)?full\b[^()]*\burl\b/.test(help) ||
+        /\bor\s+url\b/.test(help) ||
+        /\burl\s*,\s*or\b/.test(help)
+    );
+}
+
+function isIdColumn(col, detailCommands) {
+    if (ID_COLUMN_PATTERNS.some((re) => re.test(col))) return true;
+    if (/^url$/i.test(col)) {
+        return detailCommands.some(isUrlDetailCommand);
+    }
+    return false;
+}
+
+function classify(name) {
+    if (LISTING_NAMES.has(name)) return 'listing';
+    if (DETAIL_NAMES.has(name)) return 'detail';
+    return 'other';
+}
+
+function main() {
+    const manifest = JSON.parse(readFileSync(MANIFEST, 'utf8'));
+
+    const bySite = new Map();
+    for (const entry of manifest) {
+        if (!entry?.site || !entry?.name) continue;
+        if (!bySite.has(entry.site)) bySite.set(entry.site, []);
+        bySite.get(entry.site).push(entry);
+    }
+
+    const findings = [];
+    let scannedSites = 0;
+    let scannedListings = 0;
+
+    for (const [site, entries] of bySite) {
+        // Only `access: 'read'` detail commands count — write commands like
+        // `instagram/post` or `instagram/note` create remote state, they don't
+        // fetch by id, so the listing→detail pairing rule doesn't apply.
+        const readDetail = entries.filter(
+            (e) => classify(e.name) === 'detail' && e.access === 'read',
+        );
+        const hasListing = entries.some((e) => classify(e.name) === 'listing');
+        if (!hasListing || readDetail.length === 0) continue;
+        scannedSites++;
+
+        for (const entry of entries) {
+            if (classify(entry.name) !== 'listing') continue;
+            scannedListings++;
+            const columns = Array.isArray(entry.columns) ? entry.columns : [];
+            if (!columns.some((col) => isIdColumn(col, readDetail))) {
+                findings.push({
+                    site,
+                    name: entry.name,
+                    columns,
+                    detail: readDetail.map((e) => e.name),
+                });
+            }
+        }
+    }
+
+    console.log(`Scanned ${scannedSites} site(s) with both listing and read-detail commands.`);
+    console.log(`Checked ${scannedListings} listing command(s).`);
+
+    if (findings.length === 0) {
+        console.log('OK — every listing carries an id-shaped column.');
+        return;
+    }
+
+    console.log('');
+    console.log(`Advisory: ${findings.length} listing(s) without a round-trippable id column.`);
+    console.log('Some of these are legitimate (topic strings, profile-attribute rows, UI-only');
+    console.log('sessions); others may be worth adding an id to. Use judgment, not a gate.');
+    console.log('');
+    for (const v of findings) {
+        console.log(`  • ${v.site}/${v.name}`);
+        console.log(`      columns: [${v.columns.join(', ')}]`);
+        console.log(`      detail commands on this site: ${v.detail.join(', ')}`);
+    }
+    console.log('');
+    console.log('See docs/conventions/listing-detail-id-pairing.md for context and patterns.');
+}
+
+main();

package/scripts/check-silent-column-drop.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * check-silent-column-drop.mjs — CI gate for newly introduced table-output loss.
+ *
+ * This gate intentionally uses a baseline. The repo currently has known
+ * silent-column-drop findings, and blocking every existing violation would make
+ * the first CI adoption PR too large. The invariant enforced here is:
+ *
+ *   no new silent-column-drop signatures beyond scripts/silent-column-drop-baseline.json
+ *
+ * When a follow-up sweep fixes existing violations, run:
+ *
+ *   node scripts/check-silent-column-drop.mjs --update-baseline
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, '..');
+const DIST_AUDIT = resolve(PROJECT_ROOT, 'dist', 'src', 'convention-audit.js');
+const BASELINE_PATH = resolve(__dirname, 'silent-column-drop-baseline.json');
+const UPDATE = process.argv.includes('--update-baseline');
+
+if (!existsSync(DIST_AUDIT)) {
+  console.error('dist/src/convention-audit.js not found. Run npm run build before this check.');
+  process.exit(1);
+}
+
+const { runConventionAudit } = await import(pathToFileURL(DIST_AUDIT).href);
+const report = runConventionAudit({ projectRoot: PROJECT_ROOT });
+const category = report.categories.find((item) => item.rule === 'silent-column-drop');
+const current = sortRecords((category?.violations ?? []).map(toBaselineRecord));
+
+if (UPDATE) {
+  writeFileSync(BASELINE_PATH, `${JSON.stringify(current, null, 2)}\n`);
+  console.log(`Updated ${relative(BASELINE_PATH)} with ${current.length} silent-column-drop baseline entr${current.length === 1 ? 'y' : 'ies'}.`);
+  process.exit(0);
+}
+
+if (!existsSync(BASELINE_PATH)) {
+  console.error(`${relative(BASELINE_PATH)} not found. Run node scripts/check-silent-column-drop.mjs --update-baseline.`);
+  process.exit(1);
+}
+
+const baseline = sortRecords(JSON.parse(readFileSync(BASELINE_PATH, 'utf-8')));
+const baselineSignatures = new Set(baseline.map(signature));
+const currentSignatures = new Set(current.map(signature));
+const added = current.filter((record) => !baselineSignatures.has(signature(record)));
+const resolved = baseline.filter((record) => !currentSignatures.has(signature(record)));
+
+console.log(`Silent-column-drop gate: current=${current.length}, baseline=${baseline.length}, new=${added.length}, resolved=${resolved.length}`);
+
+if (resolved.length > 0) {
+  console.log('');
+  console.log('Resolved baseline entries detected. Consider shrinking the baseline:');
+  for (const record of resolved) {
+    console.log(`  - ${record.command} ${record.file} missing=[${record.missing.join(', ')}]`);
+  }
+}
+
+if (added.length === 0) {
+  console.log('OK - no new silent-column-drop violations.');
+  process.exit(0);
+}
+
+console.log('');
+console.log('New silent-column-drop violations:');
+for (const record of added) {
+  console.log(`  - ${record.command} ${record.file} missing=[${record.missing.join(', ')}]`);
+}
+console.log('');
+console.log('Fix the adapter columns, or if this is an intentional baseline adoption, run:');
+console.log('  node scripts/check-silent-column-drop.mjs --update-baseline');
+process.exit(1);
+
+function toBaselineRecord(violation) {
+  const missing = Array.isArray(violation.details?.missing)
+    ? violation.details.missing.map(String).sort()
+    : [];
+  return {
+    command: String(violation.command ?? ''),
+    file: String(violation.file ?? ''),
+    missing,
+  };
+}
+
+function signature(record) {
+  return `${record.command}\0${record.file}\0${record.missing.join('\0')}`;
+}
+
+function sortRecords(records) {
+  return records
+    .map((record) => ({
+      command: String(record.command),
+      file: String(record.file),
+      missing: Array.isArray(record.missing) ? record.missing.map(String).sort() : [],
+    }))
+    .sort((a, b) => signature(a).localeCompare(signature(b)));
+}
+
+function relative(file) {
+  return file.replace(`${PROJECT_ROOT}/`, '');
+}

package/scripts/check-typed-error-lint.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * check-typed-error-lint.mjs — CI gate for newly introduced silent failures.
+ *
+ * Baseline mode keeps adoption small: existing findings are recorded in
+ * scripts/typed-error-lint-baseline.json, while CI rejects any new
+ * silent-clamp / silent-empty-fallback / silent-sentinel signatures.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, '..');
+const DIST_AUDIT = resolve(PROJECT_ROOT, 'dist', 'src', 'convention-audit.js');
+const BASELINE_PATH = resolve(__dirname, 'typed-error-lint-baseline.json');
+const UPDATE = process.argv.includes('--update-baseline');
+const RULES = new Set(['silent-clamp', 'silent-empty-fallback', 'silent-sentinel']);
+
+if (!existsSync(DIST_AUDIT)) {
+  console.error('dist/src/convention-audit.js not found. Run npm run build before this check.');
+  process.exit(1);
+}
+
+const { runConventionAudit } = await import(pathToFileURL(DIST_AUDIT).href);
+const report = runConventionAudit({ projectRoot: PROJECT_ROOT });
+const current = addOccurrenceIndexes(sortRecords(report.categories
+  .filter((category) => RULES.has(category.rule))
+  .flatMap((category) => category.violations.map(toBaselineRecord))));
+
+if (UPDATE) {
+  writeFileSync(BASELINE_PATH, `${JSON.stringify(current, null, 2)}\n`);
+  console.log(`Updated ${relative(BASELINE_PATH)} with ${current.length} typed-error lint baseline entr${current.length === 1 ? 'y' : 'ies'}.`);
+  process.exit(0);
+}
+
+if (!existsSync(BASELINE_PATH)) {
+  console.error(`${relative(BASELINE_PATH)} not found. Run node scripts/check-typed-error-lint.mjs --update-baseline.`);
+  process.exit(1);
+}
+
+const baseline = addOccurrenceIndexes(sortRecords(JSON.parse(readFileSync(BASELINE_PATH, 'utf-8'))));
+const baselineSignatures = new Set(baseline.map(signature));
+const currentSignatures = new Set(current.map(signature));
+const added = current.filter((record) => !baselineSignatures.has(signature(record)));
+const resolved = baseline.filter((record) => !currentSignatures.has(signature(record)));
+
+console.log(`Typed-error lint gate: current=${current.length}, baseline=${baseline.length}, new=${added.length}, resolved=${resolved.length}`);
+
+if (resolved.length > 0) {
+  console.log('');
+  console.log('Resolved baseline entries detected. Consider shrinking the baseline:');
+  for (const record of resolved) {
+    console.log(`  - ${record.rule} ${record.command} ${record.file}:${record.line}`);
+  }
+}
+
+if (added.length === 0) {
+  console.log('OK - no new typed-error lint violations.');
+  process.exit(0);
+}
+
+console.log('');
+console.log('New typed-error lint violations:');
+for (const record of added) {
+  console.log(`  - ${record.rule} ${record.command} ${record.file}:${record.line}`);
+  if (record.text) console.log(`    ${record.text}`);
+}
+console.log('');
+console.log('Fix the silent fallback, or if this is an intentional baseline adoption, run:');
+console.log('  node scripts/check-typed-error-lint.mjs --update-baseline');
+process.exit(1);
+
+function toBaselineRecord(violation) {
+  return {
+    rule: String(violation.rule ?? ''),
+    command: String(violation.command ?? ''),
+    file: String(violation.file ?? ''),
+    line: Number(violation.line ?? 0),
+    text: String(violation.details?.text ?? ''),
+  };
+}
+
+function signature(record) {
+  return `${record.rule}\0${record.command}\0${record.file}\0${record.text}\0${record.occurrence}`;
+}
+
+function sortRecords(records) {
+  return records
+    .map((record) => ({
+      rule: String(record.rule),
+      command: String(record.command),
+      file: String(record.file),
+      line: Number(record.line ?? 0),
+      text: String(record.text ?? ''),
+      occurrence: Number(record.occurrence ?? 0),
+    }))
+    .sort((a, b) => stableOrder(a).localeCompare(stableOrder(b)));
+}
+
+function addOccurrenceIndexes(records) {
+  const seen = new Map();
+  return records.map((record) => {
+    const key = `${record.rule}\0${record.command}\0${record.file}\0${record.text}`;
+    const occurrence = seen.get(key) ?? 0;
+    seen.set(key, occurrence + 1);
+    return { ...record, occurrence };
+  });
+}
+
+function stableOrder(record) {
+  return `${record.rule}\0${record.command}\0${record.file}\0${record.text}\0${record.line}`;
+}
+
+function relative(file) {
+  return file.replace(`${PROJECT_ROOT}/`, '');
+}