tackbox 0.1.0 → 0.1.63

package/README.md

@@ -8,6 +8,15 @@
 
 **Every failure must report, propagate, or explain itself.**
 
+tackbox is a guardrail for developers and coding agents. It catches common
+local ways failures are hidden by accident, haste, or expediency and
+requires an explicit outcome: propagate, report, or explain. It is not a
+whole-program proof or a security boundary.
+
+tackbox's lint contract recognizes direct reporting helpers as an explicit
+report outcome. Execution policy, control flow, result ownership, and runtime
+integration remain application decisions.
+
 Coding agents write error handling that looks right and silently
 isn't: a swallowed exception, a fatal exit with nothing logged, a
 report with the cause stripped out. tackbox catches it the moment
@@ -15,9 +24,9 @@ it's written: hooked into the agent's edit loop it flags the finding
 before the turn ends, and the same rules gate pre-commit and CI -
 one coverage bar for hand-written and agent-written code.
 
-And there is no quiet way around any of it: no flags, no config. The
-only escape is an explicit `// no-report: <reason>` at the site - and
-the agent hook asks for your approval before a new suppression lands.
+There are no per-rule disable flags. A local exception stays visible as
+a reasoned `// no-report: <reason>` marker at the site, and the agent
+hook asks for your approval before a new suppression lands.
 
 ```go
 resp, err := client.Do(req)
@@ -174,7 +183,7 @@ fetched separately and cached per version:
 
 After the first fetch tackbox runs fully offline until the engine
 version changes. Platform wheels cover Linux x86_64/arm64 (manylinux),
-macOS x86_64/arm64, and Windows x86_64. `engines.json` in the thin
+macOS arm64, and Windows x86_64. `engines.json` in the thin
 wheel records the source, version, sha256, and license of every
 bundled binary and dependency; `tackbox doctor` fetches the store if
 absent and verifies the payload against it.
@@ -187,9 +196,8 @@ test-skip rules (via the `pyrules` flake8 plugin), frontend swallow,
 notify, and test-skip rules (JS, TS, Svelte, via ESLint), and Markdown
 (MD001-060 + ASCII).
 
-See `go/README.md` for the Go ruleset. The specs these rules implement
-(`error-reporting-and-coverage`, `error-handling-frontend`) live
-outside this repo (private notes); the public summary:
+See `go/README.md` for the complete Go ruleset. Across supported
+languages, the core policy is:
 
 - Every `err != nil` branch must propagate, capture, or carry an
   explicit `// no-report: <reason>` marker.
@@ -201,8 +209,9 @@ outside this repo (private notes); the public summary:
 - Bare `return nil` from a single-result function must carry
   `// nil-return: <reason>` or use `(val, ok)` / `(val, err)`.
 - A single err-branch may not both capture and `return err`.
-- Capture-call arguments must not carry raw user input, and the
-  dedupKey must be a well-formed literal.
+- The dedupKey must be a well-formed literal; in Go, capture-call
+  arguments must additionally not carry raw user input (a
+  `*http.Request` field).
 - A `notify` (user lane only, no capture) may terminate a failure path
   only when it is narrowed: a narrow catch type (Java/Python) or an
   additional condition inside the branch (Go/JS). An unconditional
@@ -361,20 +370,11 @@ on a non-Go file is rejected - a dead line would be silent. The format
 is language-uniform; the restriction lifts as other engines adopt the
 contract.
 
-## Deduplication: telemetry, never the user
-
-Dedup lives at two levels with different owners
-(`docs/report-contracts.md` D005):
+## Runtime reporting helpers
 
-- The capture helpers rate-limit telemetry: repeat captures with the
-  same dedupKey inside the rate window (default 60s) are not re-sent.
-  Lossless - the server groups by fingerprint and counts repeats.
-- The user lane is never suppressed by the helpers. Every user-facing
-  event is delivered carrying its dedupKey; collapsing a storm into
-  one live banner or a counter is presentation policy and belongs to
-  the app's listener, keyed on that dedupKey. A notification dropped
-  inside the helper would be a swallowed error at the UI level - the
-  exact failure mode tackbox exists to prevent.
+Direct reporting helpers ship per language; their shared runtime behavior -
+lane routing, telemetry dedup, panic grouping, and capture isolation - is
+specified in [docs/report-contracts.md](docs/report-contracts.md).
 
 ## Agent hook (Claude Code)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tackbox",
-  "version": "0.1.0",
-  "description": "ESLint plugin + browser report helper: every failure must report, propagate, or explain itself.",
+  "version": "0.1.63",
+  "description": "ESLint and Markdown lint plugins plus direct error-reporting helpers for JavaScript and TypeScript.",
   "license": "MIT",
   "main": "./js/eslint-plugin.js",
   "exports": {
@@ -13,7 +13,11 @@
     "tackbox-mdlint": "./bin/tackbox-mdlint.js"
   },
   "files": [
-    "js/",
+    "js/eslint-plugin.js",
+    "js/report.js",
+    "js/rules/",
+    "js/markdownlint-rules/",
+    "js/README.md",
     "bin/",
     "eslint.config.preset.js"
   ],

package/js/tests/eslint-wrapper.test.js

@@ -1,53 +0,0 @@
-const path = require('node:path')
-const os = require('node:os')
-const fs = require('node:fs')
-const { spawnSync } = require('node:child_process')
-const { test } = require('node:test')
-const assert = require('node:assert/strict')
-
-const WRAPPER = path.resolve(__dirname, '..', '..', 'bin', 'tackbox-eslint.js')
-
-// An empty catch defeated by an inline eslint-disable. The hermetic wrapper must
-// ignore the directive (allowInlineConfig: false) so the swallow still fails the
-// run: an inline disable is an uninventoried, ungated bypass of every JS rule,
-// invisible to `tackbox escapes` and the approval gate.
-const DISABLED_SWALLOW = [
-  'function handler() {',
-  '  try {',
-  '    doThing()',
-  '  // eslint-disable-next-line tackbox/no-swallow-catch',
-  '  } catch (e) {',
-  '  }',
-  '}',
-  '',
-].join('\n')
-
-function inTmpDir(body) {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tackbox-eslint-'))
-  fs.writeFileSync(path.join(dir, 'bad.js'), DISABLED_SWALLOW)
-  try {
-    return body(dir)
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true })
-  }
-}
-
-function runWrapper(dir, args) {
-  return spawnSync('node', [WRAPPER, ...args, 'bad.js'], { cwd: dir, encoding: 'utf8' })
-}
-
-test('inline eslint-disable cannot silence a swallow (default mode)', () => {
-  inTmpDir(dir => {
-    const r = runWrapper(dir, [])
-    assert.equal(r.status, 1, r.stdout + r.stderr)
-    assert.match(r.stdout, /no-swallow-catch/)
-  })
-})
-
-test('inline eslint-disable cannot silence a swallow (--machine mode)', () => {
-  inTmpDir(dir => {
-    const r = runWrapper(dir, ['--machine'])
-    assert.equal(r.status, 1, r.stdout + r.stderr)
-    assert.match(r.stdout, /no-swallow-catch/)
-  })
-})

package/js/tests/mdlint-wrapper.test.js

@@ -1,85 +0,0 @@
-const { test } = require('node:test')
-const assert = require('node:assert/strict')
-const { spawnSync } = require('node:child_process')
-const { mkdtempSync, writeFileSync, rmSync } = require('node:fs')
-const { tmpdir } = require('node:os')
-const path = require('node:path')
-
-const WRAPPER = path.resolve(__dirname, '..', '..', 'bin', 'tackbox-mdlint.js')
-
-function withTmp(fn) {
-  const dir = mkdtempSync(path.join(tmpdir(), 'tackbox-mdlint-'))
-  try { return fn(dir) } finally { rmSync(dir, { recursive: true, force: true }) }
-}
-
-function lintInTmp(dir, file) {
-  return spawnSync('node', [WRAPPER, file], { cwd: dir, encoding: 'utf8' })
-}
-
-test('ignores consumer .markdownlint.json that disables defaults', () => {
-  withTmp(dir => {
-    writeFileSync(path.join(dir, '.markdownlint.json'), '{"default": false}')
-    writeFileSync(path.join(dir, 'bad.md'), '# hi\n\nrocket: \u{1F680}\n')
-    const r = lintInTmp(dir, 'bad.md')
-    assert.equal(r.status, 1, r.stdout + r.stderr)
-    assert.match(r.stdout, /no-non-ascii/)
-    assert.match(r.stdout, /U\+1F680/)
-  })
-})
-
-test('rejects inline markdownlint-disable for the ASCII rule', () => {
-  withTmp(dir => {
-    const md = [
-      '# hi',
-      '',
-      '<!-- markdownlint-disable no-non-ascii -->',
-      '',
-      'still flagged: \u{2014}',
-      '',
-    ].join('\n')
-    writeFileSync(path.join(dir, 'bad.md'), md)
-    const r = lintInTmp(dir, 'bad.md')
-    assert.equal(r.status, 1, r.stdout + r.stderr)
-    assert.match(r.stdout, /U\+2014/)
-  })
-})
-
-test('exits 0 on clean ASCII file', () => {
-  withTmp(dir => {
-    writeFileSync(path.join(dir, 'ok.md'), '# clean\n\nplain ASCII only.\n')
-    const r = lintInTmp(dir, 'ok.md')
-    assert.equal(r.status, 0, r.stdout + r.stderr)
-    assert.equal(r.stdout, '')
-  })
-})
-
-// End-to-end (default rules + noInlineConfig): the lang marker survives the
-// real CLI path, not just the rule unit tests.
-
-const PRIVET = '\u{41F}\u{440}\u{438}\u{432}\u{435}\u{442}' // "Privet" (hello)
-const MIR = '\u{43C}\u{438}\u{440}' // "mir" (world)
-
-test('ru marker: Russian prose passes the real wrapper clean', () => {
-  withTmp(dir => {
-    writeFileSync(
-      path.join(dir, 'ru.md'),
-      '<!-- tackbox: lang=ru personal repo -->\n\n# notes\n\n' + PRIVET + ' \u{2014} ' + MIR + '.\n'
-    )
-    const r = lintInTmp(dir, 'ru.md')
-    assert.equal(r.status, 0, r.stdout + r.stderr)
-    assert.equal(r.stdout, '')
-  })
-})
-
-test('ru marker still flags an emoji, not the Cyrillic', () => {
-  withTmp(dir => {
-    writeFileSync(
-      path.join(dir, 'ru.md'),
-      '<!-- tackbox: lang=ru note -->\n\n# notes\n\n' + PRIVET + ' \u{1F680}\n'
-    )
-    const r = lintInTmp(dir, 'ru.md')
-    assert.equal(r.status, 1, r.stdout + r.stderr)
-    assert.match(r.stdout, /U\+1F680/)
-    assert.doesNotMatch(r.stdout, /U\+41F/)
-  })
-})

package/js/tests/no-non-ascii.test.js

@@ -1,124 +0,0 @@
-const { test } = require('node:test')
-const assert = require('node:assert/strict')
-const { lint } = require('markdownlint/promise')
-const rule = require('../markdownlint-rules/no-non-ascii')
-
-async function run(markdown) {
-  const out = await lint({
-    strings: { 'in.md': markdown },
-    config: { default: false, 'no-non-ascii': true },
-    customRules: [rule],
-  })
-  return out['in.md']
-}
-
-test('passes on pure ASCII content', async () => {
-  const errs = await run([
-    '# heading',
-    '',
-    'A paragraph with - dash, "quotes", `code`, and 0x7f end.',
-    '',
-    '```bash',
-    'echo hi',
-    '```',
-  ].join('\n'))
-  assert.equal(errs.length, 0)
-})
-
-test('flags assorted non-ASCII (em-dash, curly, Cyrillic, box)', async () => {
-  const errs = await run('em \u{2014} curly \u{201C}x\u{201D} hi \u{43F}\n\u{251C}\n')
-  const hexes = errs.map(e => e.errorDetail.match(/U\+([0-9A-F]+)/)[1])
-  assert.deepEqual(hexes, ['2014', '201C', '201D', '43F', '251C'])
-})
-
-test('flags non-ASCII inside fenced code blocks', async () => {
-  const errs = await run('```text\nhello \u{2014} world\n```\n')
-  assert.equal(errs.length, 1)
-  assert.equal(errs[0].lineNumber, 2)
-})
-
-test('reports column position and astral codepoints', async () => {
-  const errs = await run('abc\u{1F680}xyz\n')
-  assert.equal(errs.length, 1)
-  assert.match(errs[0].errorDetail, /U\+1F680/)
-  assert.deepEqual(errs[0].errorRange, [4, 2])
-})
-
-// -- lang marker ----------------------------------------------------------
-
-// Cyrillic building blocks, written as \u escapes so this source stays ASCII.
-const PRIVET = '\u{41F}\u{440}\u{438}\u{432}\u{435}\u{442}' // "Privet" (hello)
-const MIR = '\u{43C}\u{438}\u{440}' // "mir" (world)
-
-function detailHexes(errs) {
-  return errs.map(e => e.errorDetail.match(/U\+([0-9A-F]+)/)[1])
-}
-
-test('ru marker widens the alphabet: Russian prose + typography + ASCII code -> clean', async () => {
-  const md = [
-    '<!-- tackbox: lang=ru personal experimental repo -->',
-    '# ' + PRIVET,
-    '',
-    // em-dash, guillemets, ellipsis, NBSP all allowed under ru
-    PRIVET + ' \u{2014} \u{AB}' + MIR + '\u{BB}\u{2026}\u{A0}end',
-    '',
-    '```bash',
-    'echo hi',
-    '```',
-  ].join('\n')
-  const errs = await run(md)
-  assert.equal(errs.length, 0, JSON.stringify(errs))
-})
-
-test('ru marker still flags emoji and CJK, and only those', async () => {
-  const md = [
-    '<!-- tackbox: lang=ru note -->',
-    PRIVET + ' \u{1F680} \u{4E2D}', // rocket + CJK amid allowed Cyrillic
-  ].join('\n')
-  const errs = await run(md)
-  assert.deepEqual(detailHexes(errs), ['1F680', '4E2D'])
-})
-
-test('no marker: Cyrillic is still flagged (default unchanged)', async () => {
-  const errs = await run(PRIVET + '\n')
-  assert.deepEqual(detailHexes(errs), ['41F', '440', '438', '432', '435', '442'])
-})
-
-test('marker below line 5 is a finding and does not widen', async () => {
-  const md = [
-    'line 1', 'line 2', 'line 3', 'line 4', 'line 5',
-    '<!-- tackbox: lang=ru too late -->',
-    PRIVET, // line 7
-  ].join('\n')
-  const errs = await run(md)
-  const placement = errs.find(e => /within the first 5 lines/.test(e.errorDetail))
-  assert.ok(placement, 'expected a marker-placement finding: ' + JSON.stringify(errs))
-  assert.equal(placement.lineNumber, 6)
-  // File stays ASCII-only, so the Cyrillic on line 7 is still flagged.
-  assert.ok(errs.some(e => e.lineNumber === 7 && /U\+41F/.test(e.errorDetail)))
-})
-
-test('duplicate marker is a finding and leaves the file ASCII-only', async () => {
-  const md = [
-    '<!-- tackbox: lang=ru first -->',
-    '<!-- tackbox: lang=ru second -->',
-    PRIVET,
-  ].join('\n')
-  const errs = await run(md)
-  const dup = errs.filter(e => /duplicate tackbox lang marker/.test(e.errorDetail))
-  assert.equal(dup.length, 1)
-  assert.equal(dup[0].lineNumber, 2)
-  assert.ok(errs.some(e => /U\+41F/.test(e.errorDetail)), 'Cyrillic still flagged')
-})
-
-test('unknown language code is a finding and does not widen', async () => {
-  const errs = await run('<!-- tackbox: lang=xx -->\n' + PRIVET + '\n')
-  assert.ok(errs.some(e => /unsupported language code 'xx'/.test(e.errorDetail)))
-  assert.ok(errs.some(e => /U\+41F/.test(e.errorDetail)))
-})
-
-test('marker with no language code is a finding and does not widen', async () => {
-  const errs = await run('<!-- tackbox: lang= -->\n' + PRIVET + '\n')
-  assert.ok(errs.some(e => /missing a language code/.test(e.errorDetail)))
-  assert.ok(errs.some(e => /U\+41F/.test(e.errorDetail)))
-})

package/js/tests/report.test.js

@@ -1,182 +0,0 @@
-const { test } = require('node:test')
-const assert = require('node:assert')
-
-// report.js reads console, window/CustomEvent, and @sentry/browser at call time
-// (globals + the shared module cache), so replacing them here reaches the module
-// under test. A fake Sentry in require.cache dodges real init/network; load()
-// reloads report.js per scenario for pristine ready/lastSent state.
-const REPORT_PATH = require.resolve('../report.js')
-const SENTRY_PATH = require.resolve('@sentry/browser')
-
-console.log = () => {}
-console.warn = () => {}
-console.error = () => {}
-
-let captured = [] // one entry per Sentry.captureException: { err, level, fingerprint, tags }
-let dispatched = [] // one entry per window.dispatchEvent: the CustomEvent detail
-let scope = null
-
-const fakeSentry = {
-  init() {},
-  withScope(fn) {
-    scope = { level: undefined, fingerprint: undefined, tags: {} }
-    fn({
-      setLevel(l) { scope.level = l },
-      setFingerprint(f) { scope.fingerprint = f },
-      setTag(k, v) { scope.tags[k] = v },
-    })
-    scope = null
-  },
-  captureException(err) {
-    captured.push({
-      err,
-      level: scope && scope.level,
-      fingerprint: scope && scope.fingerprint,
-      tags: scope ? { ...scope.tags } : null,
-    })
-  },
-}
-require.cache[SENTRY_PATH] = { id: SENTRY_PATH, filename: SENTRY_PATH, loaded: true, exports: fakeSentry }
-
-class FakeCustomEvent {
-  constructor(type, opts) {
-    this.type = type
-    this.detail = opts && opts.detail
-  }
-}
-Object.defineProperty(globalThis, 'CustomEvent', { value: FakeCustomEvent, configurable: true, writable: true })
-Object.defineProperty(globalThis, 'window', {
-  value: { addEventListener() {}, dispatchEvent(ev) { dispatched.push(ev.detail); return true } },
-  configurable: true,
-  writable: true,
-})
-
-const VALID_DSN = 'https://public@sentry.example.com/1'
-
-function load() {
-  captured = []
-  dispatched = []
-  scope = null
-  delete require.cache[REPORT_PATH]
-  return require(REPORT_PATH)
-}
-
-// (a) DSN unset -> not ready -> capture disabled, but the user lane still fires.
-test('report dispatches to the user lane even when not ready (DSN unset)', () => {
-  const report = load()
-  report.init({})
-  assert.equal(report.isReady(), false)
-  report.reportError('connection lost mid-stream', new Error('boom'), { area: 'net' }, 'net.conn')
-  assert.equal(dispatched.length, 1, 'user lane must dispatch without init')
-  assert.equal(captured.length, 0, 'capture stays gated off when not ready')
-  assert.equal(dispatched[0].msg, 'connection lost mid-stream')
-  assert.equal(dispatched[0].dedupKey, 'net.conn')
-})
-
-// (b) same dedupKey inside the rate window: both dispatch, second capture dropped.
-test('rate window drops the second capture but never the dispatch', () => {
-  const report = load()
-  report.init({ dsn: VALID_DSN })
-  assert.equal(report.isReady(), true)
-  report.reportError('poll failed on stale token', new Error('e1'), { area: 'poll' }, 'poll.stale')
-  report.reportError('poll failed on stale token', new Error('e2'), { area: 'poll' }, 'poll.stale')
-  assert.equal(dispatched.length, 2, 'every event reaches the user lane')
-  assert.equal(captured.length, 1, 'duplicate capture suppressed within the window')
-})
-
-// (D-5) re-entrancy guard: a throwing tackbox:error listener surfaces via
-// window.onerror, which setupGlobalHandlers turns back into reportError ->
-// dispatch on the same stack. The guard skips the nested dispatch so it cannot
-// loop; sequential dispatches are unaffected.
-test('a re-entering dispatch is skipped (no infinite loop, one outer dispatch)', () => {
-  const report = load()
-  report.init({})
-  let calls = 0
-  const realWindow = window
-  Object.defineProperty(globalThis, 'window', {
-    value: {
-      addEventListener() {},
-      dispatchEvent(ev) {
-        calls++
-        dispatched.push(ev.detail)
-        // the listener failure re-enters synchronously via reportError
-        report.reportError('re-entry from a listener failure', new Error('inner'), null, 'reentry.key')
-        return true
-      },
-    },
-    configurable: true,
-    writable: true,
-  })
-  try {
-    report.reportError('outer dispatch that re-enters', new Error('outer'), null, 'outer.key')
-    assert.equal(calls, 1, 'exactly one dispatch; the nested re-entry is skipped')
-    assert.equal(dispatched.length, 1, 'only the outer notice reaches the user lane')
-  } finally {
-    Object.defineProperty(globalThis, 'window', { value: realWindow, configurable: true, writable: true })
-  }
-})
-
-// (c) reportPanic routes to the user lane with level fatal and a per-name key.
-test('reportPanic dispatches level fatal with panic:<name> dedupKey', () => {
-  const report = load()
-  report.reportPanic('worker', new Error('kaboom'))
-  assert.equal(dispatched.length, 1)
-  const d = dispatched[0]
-  assert.equal(d.level, 'fatal')
-  assert.equal(d.dedupKey, 'panic:worker')
-  assert.equal(d.msg, 'panic in worker')
-  assert.equal(d.cause.message, 'kaboom')
-})
-
-// (d) capture builds Error(msg) with the original error chained as .cause (seed shape).
-test('capture is Error(msg) with the original cause chained', () => {
-  const report = load()
-  report.init({ dsn: VALID_DSN })
-  const original = new Error('socket hangup')
-  report.reportError('upload failed mid-flight', original, { area: 'upload' }, 'upload.fail')
-  assert.equal(captured.length, 1)
-  const { err, level, fingerprint, tags } = captured[0]
-  assert.ok(err instanceof Error)
-  assert.equal(err.message, 'upload failed mid-flight')
-  assert.equal(err.cause, original)
-  assert.equal(level, 'error')
-  assert.deepEqual(fingerprint, ['upload.fail'])
-  assert.equal(tags.area, 'upload')
-})
-
-// (e) reportSynthError captures a plain Error(msg) with no cause chain.
-test('reportSynthError captures Error(msg) with no cause', () => {
-  const report = load()
-  report.init({ dsn: VALID_DSN })
-  report.reportSynthError('non-OK response handled inline', { area: 'http' }, 'http.synth')
-  assert.equal(captured.length, 1)
-  assert.equal(captured[0].err.message, 'non-OK response handled inline')
-  assert.equal(captured[0].err.cause, undefined)
-  assert.equal(dispatched.length, 1)
-  assert.equal(dispatched[0].cause, null, 'synth user-lane detail carries cause: null')
-})
-
-// (f) reportQuiet captures at warning with no user-lane dispatch.
-test('reportQuiet captures warning-level with no user-lane dispatch', () => {
-  const report = load()
-  report.init({ dsn: VALID_DSN })
-  report.reportQuiet('index rebuild degraded, using stale', new Error('timeout'), { area: 'idx' }, 'idx.stale')
-  assert.equal(captured.length, 1, 'quiet still captures')
-  assert.equal(captured[0].level, 'warning')
-  assert.deepEqual(captured[0].fingerprint, ['idx.stale'])
-  assert.equal(dispatched.length, 0, 'quiet must not touch the user lane')
-})
-
-// (g) notify dispatches only, captures nothing, and consumes no rate slot.
-test('notify dispatches level notice, captures nothing, leaves the rate slot', () => {
-  const report = load()
-  report.init({ dsn: VALID_DSN })
-  report.notify('you appear to be offline', new Error('net down'), { area: 'conn' }, 'conn.offline')
-  assert.equal(dispatched.length, 1)
-  assert.equal(dispatched[0].level, 'notice')
-  assert.equal(captured.length, 0, 'notify captures nothing')
-  // Same dedupKey still captures: notify consumed no rate slot.
-  report.reportError('still offline after retry', new Error('net down'), { area: 'conn' }, 'conn.offline')
-  assert.equal(captured.length, 1, 'following reportError on the notify key still captures')
-  assert.equal(dispatched.length, 2)
-})