New:Socket for Asana Is Now Available.Learn more →
Sign In

@erclx/aitk

Package Overview
Dependencies
Maintainers
1
Versions
157
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@erclx/aitk - npm Package Compare versions

Comparing version
3.3.0
 to
3.4.0
+57
docs/agents/superseded.md
---
title: Superseded values
description: Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the exemption marker, the blind spot it cannot reach, and why it reports rather than gates
---
# Superseded values
`aitk gov superseded <superseded> <replacement>` reports where the tree still asserts a value the convention behind it no longer produces. It answers the case a diff cannot: a convention changes, and the declarations testing it keep asserting the old form with nothing pointing at them.
```bash
aitk gov superseded feature-feat- feature-
aitk gov superseded feature-feat- feature- --json
aitk gov superseded old-name new-name --root ../my-app
```
| Option | Behavior |
| --------------- | ---------------------------------------------------------- |
| `--root <path>` | Tree to read, defaulting to the current directory |
| `--json` | Add a machine-readable record on stdout, keeping the frame |
Under `--json` the record holds stdout alone and the frame still renders on stderr, refusals included, which is the split `output-shape.md` fixes for every mode.
## Why the value is the key
A file-scoped map from the changed rule to what cites it reaches nothing here. A fixture asserting an old output names neither the rule nor the standard behind it, so the change that superseded the value touches no file the fixture can be found from. The value both sides carry is the only key there is.
The slug transform is what proved it. Dropping the type segment left four fixtures and three scenario scripts asserting the type-carrying spelling. One surfaced as a red sandbox arm, which named a failing scenario rather than a stale declaration, and the other six were found by deriving from the rule rather than by anything reporting them.
## What it reads
The whole corpus git lists: tracked files plus untracked ones git does not ignore. The untracked half keeps a file added on this branch in scope rather than one push later.
Matching is a literal substring, so a value carrying regular-expression characters means what it says. Every occurrence on a line reports under its own column, since a line carrying the value twice is two edits.
Binary files are skipped on a NUL byte rather than on an extension list, and so is any listed path that will not open. Both are counted. A run states the files it opened against the files git listed, because a count of what passed reads as a verdict on the repository unless it also says how much it left out.
Pass an empty replacement to retire a value outright, as in `aitk gov superseded feature-feat- ""`. Findings report the same way and none is annotated, since a line cannot carry a replacement that does not exist.
## The exemption marker
A declaration disagreeing with a convention for a stated reason carries `aitk-allow-superseded: <reason>` on its own line or the one directly above. The marker moves the line into the report's `Exempt` section, which is named rather than counted, so a reader weighing the report can reach the reason.
Only a marker naming a reason counts. A bare token is a line that meant to say something and did not, and honoring it would let a typo mute a finding. This is the `aitk-allow-secret` shape, and both read the same placement rule through one helper.
## The blind spot
The sweep sees the value and nothing else. A prose reference that went stale without carrying it is invisible here, which is not hypothetical: alongside the mechanical instances, one declaration had gone stale by citing the wrong standard for the transform, and it matches no string this sweep could have been given.
A value sweep closes most of this class and no part of that one. The help text and the frame say so on every run, so a clean report is not read as a clean tree.
## Exit codes
Exit codes are `0` when nothing asserts the superseded value, `1` for a refusal, and `2` for at least one finding. It refuses an empty superseded value, which would match every line rather than a convention, a superseded value equal to its replacement, which means no convention changed, and a tree git cannot list, since an empty list passes each of its zero files. An empty replacement is not among them, because retiring a value is an ordinary reason to run this.
Nothing wires this into `bun run check` or into a hook. A value sweep over-reports by construction, and gating a measure carrying a known false-positive class is what teaches contributors to route around the stage. `aitk gov test-order` is the sibling precedent.
An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the JSON record's `findings` array rather than the exit when a skill consumes this.
+16
src/binary.ts
/**
* Whether the bytes are something a line scanner should not read.
*
* A NUL byte rather than an extension list, since a shipped tree carries fonts
* and images under names no scanner has reason to enumerate, and a list would
* go stale the first time a format was added. Decoded text holds no NUL, so the
* test costs one scan and never rejects source.
*
* Neutral rather than owned by either sweep that calls it. The secret scan
* shaped it and the superseded-value sweep reads the same corpus, so leaving it
* in `src/secrets/` would put a `src/gov/` dependency on the secret scanner for
* a predicate about bytes.
*/
export function isBinary(text: string): boolean {
return text.includes('\0')
}
+43
src/exempt-marker.ts
/**
* Escapes every character a regular expression would read as syntax.
*
* The token became a parameter when this was extracted, and the two callers
* pass letters and hyphens alone. That is what makes escaping cheap here rather
* than a fix for a live defect: an unescaped token holding a dot matches the
* wrong lines and one holding a parenthesis throws, and neither failure is the
* caller's to anticipate.
*/
function escapeForPattern(token: string): string {
return token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
}
/**
* Whether the line at `index` carries `token` with a reason after it, reading
* itself and the line above.
*
* Extracted from `src/secrets/marker.ts`, which shaped it, so the two sweeps
* that mute a line share one answer to where a marker may sit. Two lines rather
* than one, because a value is as often introduced by a preceding comment as
* annotated inline, and a format taking no trailing comment has nowhere else to
* put the marker. Nothing further up counts, so a marker cannot silence a block
* it does not sit on.
*
* Only a marker naming a reason counts. A bare token is read as a line that
* meant to say something and did not, and honoring it would let a typo mute a
* finding, where the reason is the whole value of an exemption a later reader
* has to weigh.
*/
export function isMarked(
lines: readonly string[],
index: number,
token: string,
): boolean {
const pattern = new RegExp(`${escapeForPattern(token)}:[ \\t]*\\S`)
const own = lines[index]
const above = index > 0 ? lines[index - 1] : undefined
return (
(own !== undefined && pattern.test(own)) ||
(above !== undefined && pattern.test(above))
)
}
+207
src/gov/superseded.ts
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
import { isBinary } from '@/binary'
import { isMarked } from '@/exempt-marker'
import { listRepositoryFiles } from '@/git-files'
/**
* The inline token exempting one line from this sweep, shaped on the
* `aitk-allow-secret` precedent and read by the same two-line rule.
*
* A declaration disagreeing with a convention for a stated reason is the case
* question 3 of the plan settled against gating on, and the marker is where
* that reason goes. A bare token names nothing a later reader can weigh, so it
* mutes nothing.
*/
export const SUPERSEDED_MARKER = 'aitk-allow-superseded'
export interface SupersededHit {
readonly file: string
/** One-based, matching the `file:line` form a reader clicks. */
readonly line: number
readonly column: number
/**
* Whether the replacement sits on the same line, outside the superseded
* occurrences themselves.
*
* Read outside them because the replacement is routinely a substring of the
* value it replaced, which is what a convention dropping a segment produces.
* A plain containment test answers true for every line under that shape and
* separates nothing.
*
* A reading aid rather than a filter. The line stating the change carries
* both values and so does a fixture halfway through a repair, and nothing
* here can tell those apart. Suppressing on it would hide the second case,
* which is the whole class this sweep exists to reach.
*/
readonly carriesReplacement: boolean
readonly preview: string
}
export interface SupersededOptions {
/** The value the convention used to produce, matched as a literal substring. */
readonly superseded: string
/** What it produces now, reported so a finding names what to write instead. */
readonly replacement: string
}
export type SupersededReport =
| {
readonly kind: 'measured'
readonly superseded: string
readonly replacement: string
/** Everything git listed, so the report states its own bound. */
readonly listed: number
/** Files opened, which is what the verdict actually covers. */
readonly files: number
/** Binary or unreadable, counted so a pass is not claimed over them. */
readonly skipped: number
readonly findings: readonly SupersededHit[]
readonly exempt: readonly SupersededHit[]
}
| { readonly kind: 'unreadable'; readonly reason: string }
/**
* The longest preview a hit carries. A generated or minified line is one line
* to git and a screen of noise to a reader, and the report prints one hit per
* line found.
*/
const PREVIEW_LIMIT = 200
/**
* Whether `replacement` appears on the line somewhere other than inside the
* superseded occurrences, which is what makes the flag mean anything when one
* value contains the other.
*
* An empty replacement carries nothing, so it answers false rather than the
* true every line returns from a containment test against the empty string.
* Retiring a value outright is what passes one, and reporting every finding as
* carrying its replacement there says the opposite of what happened.
*/
function carriesReplacement(line: string, options: SupersededOptions): boolean {
if (options.replacement === '') return false
return line.split(options.superseded).join('').includes(options.replacement)
}
/** Every occurrence of `superseded` in one file's text, exemptions separated. */
export function sweepText(
file: string,
text: string,
options: SupersededOptions,
): { findings: SupersededHit[]; exempt: SupersededHit[] } {
const lines = text.split('\n')
const findings: SupersededHit[] = []
const exempt: SupersededHit[] = []
for (const [index, line] of lines.entries()) {
let column = line.indexOf(options.superseded)
if (column === -1) continue
const muted = isMarked(lines, index, SUPERSEDED_MARKER)
const bucket = muted ? exempt : findings
const trimmed = line.trim()
const preview =
trimmed.length > PREVIEW_LIMIT
? `${trimmed.slice(0, PREVIEW_LIMIT)}…`
: trimmed
const alsoReplacement = carriesReplacement(line, options)
while (column !== -1) {
bucket.push({
file,
line: index + 1,
column: column + 1,
carriesReplacement: alsoReplacement,
preview,
})
column = line.indexOf(options.superseded, column + 1)
}
}
return { findings, exempt }
}
/**
* Where the tree still asserts a value the convention behind it no longer
* produces, keyed on the value rather than on the file stating the rule.
*
* The file-scoped map is what this exists against. A fixture asserting an old
* output names neither the rule nor the standard, so nothing reaches it from
* the change that superseded it, and the value it carries is the only key both
* sides share.
*
* This reports and never gates. A string appears for reasons unrelated to the
* convention, so the output is a reading a person settles, and the counts of
* what was listed, opened, and skipped are what keep it from reading as a
* verdict over the whole tree.
*
* What it cannot see is a prose reference that went stale without carrying the
* value, such as a declaration citing the wrong standard for the transform. A
* value sweep closes most of this class and no part of that one.
*/
export async function readSuperseded(
root: string,
options: SupersededOptions,
): Promise<SupersededReport> {
if (options.superseded === '') {
return {
kind: 'unreadable',
reason:
'The superseded value is empty, which matches every line in the tree rather than a convention.',
}
}
if (options.superseded === options.replacement) {
return {
kind: 'unreadable',
reason: `The superseded value and its replacement are both ${options.superseded}, so no convention changed and there is nothing to sweep for.`,
}
}
const listed = await listRepositoryFiles(root)
if (listed === undefined) {
return {
kind: 'unreadable',
reason: `Git listed no corpus under ${root}. An empty list passes each of its zero files, so a tree git cannot read refuses rather than reporting clean.`,
}
}
const findings: SupersededHit[] = []
const exempt: SupersededHit[] = []
let files = 0
let skipped = 0
for (const path of listed) {
let text: string
try {
text = await readFile(join(root, path), 'utf8')
} catch {
// A listed path that will not open is a symlink leaving the tree or a
// file removed since git answered. Counted rather than reported, so the
// run still states that it measured less than it listed.
skipped += 1
continue
}
if (isBinary(text)) {
skipped += 1
continue
}
files += 1
const swept = sweepText(path, text, options)
findings.push(...swept.findings)
exempt.push(...swept.exempt)
}
return {
kind: 'measured',
superseded: options.superseded,
replacement: options.replacement,
listed: listed.length,
files,
skipped,
findings,
exempt,
}
}
+1
-1
claude/.claude-plugin/plugin.json
{
"name": "aitk",
"description": "Automated governance, versioning, and discovery tools for Claude Code.",
"version": "3.3.0",
"version": "3.4.0",
"author": {

@@ -6,0 +6,0 @@ "name": "Eric Le",

+2
-1
docs/agents/commands.md

@@ -51,2 +51,3 @@ ---

| `aitk gov test-order` | Report where an implementation reached history ahead of the test covering it (`--json`) |
| `aitk gov superseded` | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value (`--json`) |
| `aitk secrets scan` | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`) |

@@ -69,3 +70,3 @@ | `aitk deps audit` | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`) |

| `standards` | `list`, `<name>` |
| `gov` | `list`, `install`, `sync`, `build`, `regen`, `test-order` |
| `gov` | `list`, `install`, `sync`, `build`, `regen`, `test-order`, `superseded` |
| `claude` | `init`, `sync`, `seeds list`, `skills list`, `skills audit`, `skills drift`, `skills reach`, `setup [dest]` |

@@ -72,0 +73,0 @@ | `wiki` | `init` |

+1
-0
docs/agents/index.md

@@ -32,4 +32,5 @@ ---

- [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
- [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the exemption marker, the blind spot it cannot reach, and why it reports rather than gates
- [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
- [Teach](teach.md): Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, the refusal reasons, and why every write here runs through a verb
- [Test order](test-order.md): Reading where an implementation reached history ahead of its test, how a pair is decided, the three verdicts, the coverage the pairing cannot reach, and why the check reports rather than gates
+1
-1
package.json
{
"name": "@erclx/aitk",
"type": "module",
"version": "3.3.0",
"version": "3.4.0",
"description": "Infrastructure and quality tooling for developer workflows",

@@ -6,0 +6,0 @@ "license": "MIT",

+146
-0
src/commands/gov.ts

@@ -18,2 +18,8 @@ import { existsSync } from 'node:fs'

import {
readSuperseded,
SUPERSEDED_MARKER,
type SupersededHit,
type SupersededReport,
} from '@/gov/superseded'
import {
type PairRecord,

@@ -61,2 +67,7 @@ readTestOrder,

interface SupersededOptions {
readonly root?: string
readonly json?: boolean
}
export function register(program: Command): void {

@@ -185,5 +196,140 @@ const gov = program

})
gov
.command('superseded')
.description(
'Report where the tree still asserts a value a changed convention no longer produces',
)
.argument('<superseded>', 'The value the convention used to produce')
.argument('<replacement>', 'What it produces now')
.helpOption('-h, --help', 'Show this help message')
.option('--root <path>', 'Tree to read, defaulting to the cwd')
.option('--json', 'Add a machine-readable record on stdout')
.addHelpText(
'after',
[
'',
'Keyed on the value rather than on the file stating the rule. A fixture',
'asserting an old output names neither the rule nor the standard behind',
'it, so a file-scoped map from the changed rule reaches none of them and',
'the value both sides carry is the only key there is.',
'',
'It reports and never gates. A string appears for reasons unrelated to',
'the convention, so the output is a reading rather than a verdict, and a',
'declaration disagreeing for a stated reason carries a',
`\`${SUPERSEDED_MARKER}: <reason>\` marker on its own line or the one above.`,
'',
'Pass an empty replacement to retire a value outright. Findings report',
'the same way and none is annotated, since a line cannot carry a',
'replacement that does not exist.',
'',
'Blind spot:',
' a prose reference that went stale without carrying the value, such as',
' a declaration citing the wrong standard for the transform, matches',
' nothing here and is reached by reading rather than by this sweep',
'',
'Exit codes:',
' 0 nothing in the corpus asserts the superseded value',
' 1 refused, with the reason on stderr or in the JSON record',
' 2 at least one declaration still asserts it',
'',
'Examples:',
' aitk gov superseded feature-feat- feature-',
' aitk gov superseded feature-feat- feature- --json',
'',
].join('\n'),
)
.action(
async (
superseded: string,
replacement: string,
opts: SupersededOptions,
) => {
process.exitCode = await runSuperseded(superseded, replacement, opts)
},
)
}
/**
* Reports and never gates, matching `test-order` above. The finding count moves
* the exit code with nothing wiring it into a push, since a value sweep
* over-reports by construction and gating a measure carrying a known
* false-positive class is what teaches contributors to route around a stage.
*/
async function runSuperseded(
superseded: string,
replacement: string,
opts: SupersededOptions,
): Promise<number> {
const root = resolve(opts.root ?? process.cwd())
const report = await readSuperseded(root, { superseded, replacement })
const emitJson = opts.json ?? false
if (report.kind === 'unreadable') {
intro('aitk gov superseded')
logStep('Refused')
logError(report.reason)
outro()
if (emitJson) {
process.stdout.write(
`${JSON.stringify({ ok: false, reason: report.reason })}\n`,
)
}
return 1
}
reportSuperseded(report, root)
if (emitJson) {
process.stdout.write(`${JSON.stringify({ ok: true, root, ...report })}\n`)
}
return report.findings.length > 0 ? 2 : 0
}
function describeHit(hit: SupersededHit): string {
const note = hit.carriesReplacement
? ' (the replacement is on this line)'
: ''
return `${hit.file}:${hit.line}:${hit.column}${note}: ${hit.preview}`
}
function reportSuperseded(
report: Extract<SupersededReport, { kind: 'measured' }>,
root: string,
): void {
intro('aitk gov superseded')
logStep('Sweep')
logInfo(`${report.superseded} → ${report.replacement} in ${root}`)
logStep(report.findings.length === 0 ? 'Clean' : 'Findings')
if (report.findings.length === 0) {
logInfo('nothing in the corpus asserts the superseded value')
} else {
for (const finding of report.findings) logWarn(describeHit(finding))
}
// Named rather than counted. A muted line is a judgment someone recorded,
// and a reader weighing this report has to be able to reach the reason.
logStep('Exempt')
if (report.exempt.length === 0) {
logInfo('no line carries a marker')
} else {
for (const hit of report.exempt) logInfo(describeHit(hit))
}
// A count of what passed reads as a verdict on the repository unless the run
// also says how much of it the corpus left out.
logStep('Corpus')
logInfo(
`${report.files} file(s) opened of ${report.listed} listed, ${report.skipped} skipped as binary or unreadable`,
)
outro()
}
/**
* Reports and never gates, so the finding count moves the exit code without

@@ -190,0 +336,0 @@ * anything wiring it into a push. `aitk tasks validate` set that shape: a

+7
-21
src/secrets/marker.ts

@@ -0,1 +1,3 @@

import { isMarked } from '@/exempt-marker'
/**

@@ -19,27 +21,11 @@ * The inline token exempting one line from the secret scan.

/**
* Only a marker naming a reason counts.
*
* A bare token is read as a line that meant to say something and did not,
* which is the rule `isStubSeed` already applies to a field set to anything
* but `true`. Honoring it would let a typo mute a finding, and the reason is
* the whole value of an exemption a later reader has to weigh.
*/
const MARKER_LINE = new RegExp(`${SECRET_MARKER}:[ \\t]*\\S`)
/**
* Whether the line at `index` is exempt, reading itself and the line above it.
*
* Two lines rather than one, because a credential-shaped literal is as often
* introduced by a preceding comment as annotated inline, and a format that
* takes no trailing comment at all has nowhere else to put the marker. Nothing
* further up counts, so a marker cannot silence a block it does not sit on.
* Where a marker may sit and what makes one count are `isMarked`, which the
* superseded-value sweep reads through the same call. Only the token differs
* between the two, so the placement rule has one answer rather than two that
* can drift.
*/
export function isExempt(lines: readonly string[], index: number): boolean {
const own = lines[index]
const above = index > 0 ? lines[index - 1] : undefined
return (
(own !== undefined && MARKER_LINE.test(own)) ||
(above !== undefined && MARKER_LINE.test(above))
)
return isMarked(lines, index, SECRET_MARKER)
}
+1
-12
src/secrets/scan.ts
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
import { isBinary } from '@/binary'
import { listRepositoryFiles } from '@/git-files'

@@ -51,14 +52,2 @@ import { isExempt } from '@/secrets/marker'

/**
* Whether the bytes are something a line scanner should not read.
*
* A NUL byte rather than an extension list, since the shipped tree carries
* fonts and images under names this check has no reason to enumerate, and a
* list would go stale the first time a format was added. Decoded text holds no
* NUL, so the test costs one scan and never rejects source.
*/
export function isBinary(text: string): boolean {
return text.includes('\0')
}
/** Every finding in one file's text, with the marker already applied. */

@@ -65,0 +54,0 @@ export function scanText(file: string, text: string): SecretFinding[] {

+8
-0
standards/slug.md

@@ -32,1 +32,9 @@ ---

- Fall through to the next source, when the slug is one candidate among several rather than the name of an output file
## Changing the transform
A change here moves what the transform produces, and every declaration asserting the old output keeps asserting it. Nothing reports those, because a fixture carrying an old filename names neither this file nor the surface that reads it, so a diff over the change reaches none of them. Dropping the type segment is the change that proved it: four fixtures and three scenario scripts kept the type-carrying spelling, one surfaced as a red arm months later, and the other six were found by deriving from the rule.
Run `aitk gov superseded <old> <new>` in the same change, with the old output and the new one as the two arguments. The value is the only key both sides carry, and the sweep reads the whole tracked tree rather than a path someone predicted. Its output is a reading rather than a verdict, since a string appears for reasons unrelated to any convention, and a declaration disagreeing on purpose carries an `aitk-allow-superseded: <reason>` marker on its own line or the one above.
The sweep sees a value and nothing else. A prose reference that went stale without carrying it, such as a passage citing the wrong standard for the transform, is reached by reading rather than by any key.