@inixiative/atlas 0.4.1 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,48 +1,87 @@
1
- import { resolve } from 'node:path';
1
+ import { existsSync, lstatSync, realpathSync } from 'node:fs';
2
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
3
+ import { consideredFiles, encodeText, readText, type TextEncoding } from '../analyze.ts';
2
4
  import type { LoadedConfig } from '../config/defineConfig.ts';
3
5
  import { loadConfig } from '../config/load.ts';
4
6
  import { stampFor } from '../config/stamp.ts';
5
7
  import { mapLimit } from '../fs/concurrent.ts';
6
- import { walkFiles } from '../fs/walk.ts';
7
- import { applyStamp, type StampMode } from '../stamp/patcher.ts';
8
+ import { applyStamp, type StampMode, type StampSkip } from '../stamp/patcher.ts';
9
+ import type { CommentStyle } from '../syntax/comments.ts';
8
10
 
9
- export type StampChange = { path: string; before: string; after: string };
11
+ // `before`/`after` are the text; `encoding` is how the file stores it (written back the same way).
12
+ export type StampChange = { path: string; before: string; after: string; encoding?: TextEncoding };
10
13
  export type Unresolved = { file: string; category: string; value: string };
11
- export type StampResult = { changes: StampChange[]; unresolved: Unresolved[] };
14
+ export type Skipped = { file: string; reason: StampSkip };
15
+ export type StampResult = { changes: StampChange[]; unresolved: Unresolved[]; skipped: Skipped[] };
12
16
 
13
17
  const IO_CONCURRENCY = 64;
14
18
 
15
- // A file is in scope when no target is given, when the target IS the file, or
16
- // when the target is a folder the file lives under. (all / folder / individual)
17
- export const inScope = (path: string, target?: string): boolean => {
18
- if (!target) return true;
19
- if (path === target) return true;
20
- const folder = target.endsWith('/') ? target : `${target}/`;
21
- return path.startsWith(folder);
19
+ // A file is in scope when no target is given, when a target IS the file, or when a target is a
20
+ // folder the file lives under. Targets are repo-relative and may be written `./src`, `src/` or
21
+ // `.` (the whole repo), as a shell or `dirname` produces them.
22
+ export const inScope = (path: string, targets: string[] = []): boolean => {
23
+ if (targets.length === 0) return true;
24
+ return targets.some((raw) => {
25
+ const target = raw.replace(/^(?:\.\/)+/, '').replace(/\/+$/, '');
26
+ if (target === '' || target === '.') return true;
27
+ return path === target || path.startsWith(`${target}/`);
28
+ });
29
+ };
30
+
31
+ // Command-line targets as repo-relative paths. A target is resolved against the repo root (an
32
+ // absolute path works too) and must exist inside it: a typo'd or outside path would otherwise
33
+ // scope a check to nothing and pass. It is read in its on-disk spelling, so `SRC/a.ts` on a
34
+ // case-insensitive disk still scopes to `src/a.ts`.
35
+ const onDisk = (path: string): string => {
36
+ const link = lstatSync(path).isSymbolicLink();
37
+ return link
38
+ ? join(realpathSync.native(dirname(path)), basename(path))
39
+ : realpathSync.native(path);
40
+ };
41
+ export const resolveTargets = (root: string, raw: string[]): string[] => {
42
+ if (raw.length === 0) return [];
43
+ if (!existsSync(root)) throw new Error(`no such directory: ${root}`);
44
+ // the root itself is resolved fully, link included (a project registered through a symlink)
45
+ const realRoot = realpathSync.native(resolve(root));
46
+ return raw.map((target) => {
47
+ const absolute = resolve(root, target);
48
+ try {
49
+ lstatSync(absolute);
50
+ } catch {
51
+ throw new Error(`no such file or folder: ${target}`);
52
+ }
53
+ // the root itself (`.`, or the root path when it is a symlink) is the whole repo
54
+ if (absolute === resolve(root)) return '.';
55
+ const rel = relative(realRoot, onDisk(absolute));
56
+ if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
57
+ throw new Error(`target is outside the repo root: ${target}`);
58
+ return rel === '' ? '.' : rel.replaceAll(sep, '/');
59
+ });
22
60
  };
23
61
 
24
62
  // Pure: what stamping a file WOULD do, or null if it's already up to date.
25
63
  export const computeStamp = (
26
- path: string,
64
+ file: { path: string; style: CommentStyle },
27
65
  source: string,
28
66
  config: LoadedConfig,
29
67
  mode: StampMode,
30
68
  ): StampChange | null => {
69
+ const { path } = file;
31
70
  const resolved = stampFor(path, config.stamp, config.concepts);
32
- const { content, changed } = applyStamp(source, resolved, mode);
71
+ const { content, changed } = applyStamp(source, resolved, file, mode);
33
72
  return changed ? { path, before: source, after: content } : null;
34
73
  };
35
74
 
36
75
  // Pure: the full change plan over an in-memory file set, scoped by target.
37
76
  export const planStamp = (
38
- files: { path: string; source: string }[],
77
+ files: { path: string; style: CommentStyle; source: string }[],
39
78
  config: LoadedConfig,
40
79
  mode: StampMode,
41
- target?: string,
80
+ targets: string[] = [],
42
81
  ): StampChange[] =>
43
82
  files
44
- .filter((f) => inScope(f.path, target))
45
- .map((f) => computeStamp(f.path, f.source, config, mode))
83
+ .filter((f) => inScope(f.path, targets))
84
+ .map((f) => computeStamp(f, f.source, config, mode))
46
85
  .filter((c): c is StampChange => c !== null);
47
86
 
48
87
  // IO: read the scoped files, plan, and (only with write) persist. Dry-run is
@@ -52,26 +91,55 @@ export const planStamp = (
52
91
  // to no concept — leaving a file under-stamped — is visible at write time.
53
92
  export const runStamp = async (
54
93
  root: string,
55
- opts: { mode: StampMode; target?: string; write: boolean },
94
+ opts: { mode: StampMode; targets?: string[]; write: boolean },
56
95
  ): Promise<StampResult> => {
57
96
  const config = await loadConfig(root);
58
- const paths = (await walkFiles(root, config.include, config.ignore)).filter((p) =>
59
- inScope(p, opts.target),
60
- );
61
- const files = await mapLimit(paths, IO_CONCURRENCY, async (path) => ({
62
- path,
63
- source: await Bun.file(resolve(root, path)).text(),
64
- }));
97
+ const scoped = (await consideredFiles(root, config)).filter((f) => inScope(f.path, opts.targets));
98
+ // A file with no comment style is tagged by its path; there is nothing to write into it.
99
+ const read = await mapLimit(scoped, IO_CONCURRENCY, async ({ path, style }) => {
100
+ if (!style) return null;
101
+ const read = await readText(root, path);
102
+ return read === null
103
+ ? null
104
+ : { path, style, source: read.text, encoding: read.encoding, exact: read.exact };
105
+ });
106
+ const files = read.filter((f) => f !== null);
65
107
 
66
- const changes = planStamp(files, config, opts.mode, opts.target);
108
+ const changes: StampChange[] = [];
109
+ const skipped: Skipped[] = [];
110
+ // the rules' result for each file, used for the stamp and for the unresolved report
111
+ const rules = new Map(
112
+ scoped.map(
113
+ (f) =>
114
+ [
115
+ f.path,
116
+ f.style === null ? f.stamp : stampFor(f.path, config.stamp, config.concepts),
117
+ ] as const,
118
+ ),
119
+ );
120
+ for (const file of files) {
121
+ const resolved = rules.get(file.path) ?? stampFor(file.path, config.stamp, config.concepts);
122
+ const result = applyStamp(file.source, resolved, file, opts.mode);
123
+ if (result.changed && !file.exact) skipped.push({ file: file.path, reason: 'encoding' });
124
+ else if (result.changed)
125
+ changes.push({
126
+ path: file.path,
127
+ before: file.source,
128
+ after: result.content,
129
+ encoding: file.encoding,
130
+ });
131
+ else if (result.skipped) skipped.push({ file: file.path, reason: result.skipped });
132
+ }
67
133
  const unresolved: Unresolved[] = [];
68
- for (const { path } of files) {
69
- for (const u of stampFor(path, config.stamp, config.concepts).unresolved) {
134
+ for (const [path, stamp] of rules) {
135
+ for (const u of stamp.unresolved) {
70
136
  unresolved.push({ file: path, category: u.category, value: u.value });
71
137
  }
72
138
  }
73
139
 
74
140
  if (opts.write)
75
- await mapLimit(changes, IO_CONCURRENCY, (c) => Bun.write(resolve(root, c.path), c.after));
76
- return { changes, unresolved };
141
+ await mapLimit(changes, IO_CONCURRENCY, (c) =>
142
+ Bun.write(resolve(root, c.path), encodeText(c.after, c.encoding ?? 'utf-8')),
143
+ );
144
+ return { changes, unresolved, skipped };
77
145
  };
@@ -1,4 +1,5 @@
1
1
  import type { ConceptRegistry, Thesaurus } from '../registry/types.ts';
2
+ import type { CommentTable } from '../syntax/comments.ts';
2
3
 
3
4
  // `partOfFor` is a LAZY descriptor, not a value. The consumer's config.ts can
4
5
  // reference it before the concept registry is loaded; the stamp engine resolves it
@@ -49,17 +50,24 @@ export type ReferenceResolver = (value: string) => string;
49
50
  type ConfigDefaults = {
50
51
  stamp: StampRule[]; // path → tag rules
51
52
  ignore: string[]; // files exempt from presence + stamping (tests, barrels)
52
- include: string[]; // file globs atlas considers (default: common source files)
53
53
  references: Record<string, ReferenceResolver>;
54
54
  };
55
55
 
56
- export type AtlasConfigInput = Partial<ConfigDefaults>;
56
+ export type AtlasConfigInput = Partial<ConfigDefaults> & {
57
+ // file globs atlas considers. Unset: every file in a comment style atlas knows, plus every
58
+ // file a stamp rule tags by its path.
59
+ include?: string[];
60
+ // more files per comment style: `{ hash: ['.nix', 'Tiltfile'] }` (`.ext` or an exact name)
61
+ comments?: CommentTable;
62
+ };
57
63
 
58
64
  export const defineConfig = (config: AtlasConfigInput): AtlasConfigInput => config;
59
65
 
60
66
  // What the loader hands the engine once defaults are applied and vocab/registry
61
67
  // are loaded from the sibling .atlas/ files.
62
68
  export type LoadedConfig = ConfigDefaults & {
69
+ include: string[] | null; // null: the default (see AtlasConfigInput.include)
70
+ comments: Required<CommentTable>; // atlas's table merged with the repo's additions
63
71
  kinds: readonly string[];
64
72
  concepts: ConceptRegistry;
65
73
  thesaurus: Thesaurus;
@@ -1,9 +1,48 @@
1
1
  import { resolve } from 'node:path';
2
- import { DEFAULT_INCLUDE } from '../fs/walk.ts';
3
2
  import type { ConceptRegistry, Thesaurus } from '../registry/types.ts';
3
+ import { COMMENT_STYLES, type CommentTable, mergeCommentTable } from '../syntax/comments.ts';
4
4
  import { DEFAULT_KINDS } from '../vocab/kinds.ts';
5
5
  import type { AtlasConfigInput, LoadedConfig } from './defineConfig.ts';
6
6
 
7
+ // `.atlas/**/*.ts` imports `@inixiative/atlas` (defineConfig, partOfFor, DEFAULT_KINDS). Bind those
8
+ // imports to the atlas that is running, so the config loads in a repo with no package.json or
9
+ // node_modules (`bunx @inixiative/atlas check` in a Python repo) and never against another
10
+ // installed version. Bun's runtime plugins ignore onResolve for bare imports, so the specifier
11
+ // is rewritten on load.
12
+ const SELF: Record<string, string> = {
13
+ '@inixiative/atlas': resolve(import.meta.dir, '../index.ts'),
14
+ '@inixiative/atlas/config': resolve(import.meta.dir, './defineConfig.ts'),
15
+ };
16
+ // only a module specifier: `from '…'`, `import '…'`, `import('…')`, never another string literal
17
+ const ATLAS_IMPORT = /(\bfrom\s*|\bimport\s*\(?\s*)(['"])(@inixiative\/atlas(?:\/config)?)\2/g;
18
+
19
+ // Rewrite a config file's atlas imports to `paths`. The path is spliced into the file's own
20
+ // string literal, so it is written with forward slashes (a Windows `\` would be read as an
21
+ // escape: `C:\Users\node_modules` → `C:Users<newline>ode_modules`; Bun accepts `C:/…`) and the
22
+ // literal's quote is escaped (an install under `O'Brien/`).
23
+ export const bindAtlasImports = (source: string, paths: Record<string, string> = SELF): string =>
24
+ source.replace(ATLAS_IMPORT, (match, keyword: string, quote: string, specifier: string) => {
25
+ const path = paths[specifier];
26
+ if (!path) return match;
27
+ return `${keyword}${quote}${path.replaceAll('\\', '/').replaceAll(quote, `\\${quote}`)}${quote}`;
28
+ });
29
+
30
+ let bound = false;
31
+ const bindSelfImports = (): void => {
32
+ if (bound) return;
33
+ bound = true;
34
+ Bun.plugin({
35
+ name: 'atlas-config-self',
36
+ target: 'bun',
37
+ setup(build) {
38
+ build.onLoad({ filter: /[\\/]\.atlas[\\/].+\.[cm]?ts$/ }, async ({ path }) => ({
39
+ loader: 'ts',
40
+ contents: bindAtlasImports(await Bun.file(path).text()),
41
+ }));
42
+ },
43
+ });
44
+ };
45
+
7
46
  // Import a `.atlas/` file if it exists; missing files are optional (atlas ships
8
47
  // defaults for vocab), but a present file with a real error propagates.
9
48
  const loadModule = async (path: string): Promise<Record<string, unknown> | null> => {
@@ -24,10 +63,26 @@ const named = <T>(
24
63
  throw new Error(`.atlas/${file} exists but exports none of: ${names.join(', ')}`);
25
64
  };
26
65
 
66
+ // `comments` names styles atlas has; a typo would silently tag nothing, so refuse it.
67
+ const validComments = (comments: CommentTable | undefined): CommentTable | undefined => {
68
+ for (const [style, entries] of Object.entries(comments ?? {})) {
69
+ if (!(style in COMMENT_STYLES))
70
+ throw new Error(
71
+ `.atlas/config.ts: comments.${style} is not a comment style (${Object.keys(COMMENT_STYLES).join(', ')})`,
72
+ );
73
+ if (!Array.isArray(entries) || entries.some((e) => typeof e !== 'string' || e === ''))
74
+ throw new Error(
75
+ `.atlas/config.ts: comments.${style} must list '.ext' extensions or file names`,
76
+ );
77
+ }
78
+ return comments;
79
+ };
80
+
27
81
  // Load the consumer's `.atlas/` config: kinds → concepts → thesaurus → config (no
28
82
  // evaluation-order coupling, since partOfFor is a lazy descriptor). atlas ships
29
83
  // the kinds defaults; the repo OWNS concepts.ts and the optional thesaurus.ts.
30
84
  export const loadConfig = async (root: string): Promise<LoadedConfig> => {
85
+ bindSelfImports();
31
86
  const dir = resolve(root, '.atlas');
32
87
  const [kindsMod, conceptsMod, thesaurusMod, configMod] = await Promise.all([
33
88
  loadModule(resolve(dir, 'kinds.ts')),
@@ -71,12 +126,13 @@ export const loadConfig = async (root: string): Promise<LoadedConfig> => {
71
126
  }
72
127
 
73
128
  return {
129
+ include: cfg.include ?? null,
130
+ comments: mergeCommentTable(validComments(cfg.comments)),
74
131
  kinds,
75
132
  concepts,
76
133
  thesaurus,
77
134
  stamp: cfg.stamp ?? [],
78
135
  ignore: cfg.ignore ?? [],
79
- include: cfg.include ?? DEFAULT_INCLUDE,
80
136
  references: cfg.references ?? {},
81
137
  };
82
138
  };
package/src/fs/walk.ts CHANGED
@@ -1,26 +1,99 @@
1
+ import { existsSync, lstatSync } from 'node:fs';
2
+ import { resolve } from 'node:path';
1
3
  import { Glob } from 'bun';
2
4
  import { matchesAny } from '../config/glob.ts';
3
5
 
4
- export const DEFAULT_INCLUDE = ['**/*.ts', '**/*.tsx'];
6
+ // Never considered, whatever the config says. Dotdirs are walked (`.claude/`, `.github/` carry
7
+ // real work); these aren't. `.atlas/` is the config itself; MAP.md, COVERAGE.md and atlas.html
8
+ // are what `generate` and `report` write (stamping one would fight the next generate); a pnpm
9
+ // lockfile is generated and pnpm strips comments from it.
10
+ export const ALWAYS_IGNORE = [
11
+ '**/node_modules/**',
12
+ '**/.git/**',
13
+ '**/dist/**',
14
+ '**/.atlas/**',
15
+ 'MAP.md', // generate writes it at the root only
16
+ '**/COVERAGE.md', // report writes these wherever --out points
17
+ '**/atlas.html',
18
+ '**/pnpm-lock.yaml',
19
+ ];
5
20
 
6
- // Never walk into these regardless of consumer config.
7
- const ALWAYS_IGNORE = ['**/node_modules/**', '**/.git/**', '**/dist/**'];
21
+ const git = async (root: string, args: string[]) => {
22
+ let proc: ReturnType<typeof Bun.spawn>;
23
+ try {
24
+ // LC_ALL=C: git's messages are read below, and a translated git words them differently
25
+ proc = Bun.spawn(['git', ...args], {
26
+ cwd: root,
27
+ stdout: 'pipe',
28
+ stderr: 'pipe',
29
+ env: { ...process.env, LC_ALL: 'C' },
30
+ });
31
+ } catch {
32
+ throw new Error('atlas lists files with git, and git is not installed');
33
+ }
34
+ const [out, err, code] = await Promise.all([
35
+ new Response(proc.stdout as ReadableStream).text(),
36
+ new Response(proc.stderr as ReadableStream).text(),
37
+ proc.exited,
38
+ ]);
39
+ return { out, err: err.trim(), code };
40
+ };
8
41
 
9
- // Repo-relative source files matching `include` and not `ignore`, sorted for
10
- // deterministic output. Dotfiles/dotdirs (including `.atlas/`) are skipped.
42
+ // What git would commit: tracked files plus untracked ones that aren't ignored, so a new file is
43
+ // seen before it's added and generated output under .gitignore never is. Null when the root is
44
+ // not part of a repo: outside any work tree, or a folder the enclosing repo ignores (a scratch
45
+ // dir). Any other git failure (`safe.directory`, a broken index) is an error, never a silent
46
+ // switch to listing every file.
47
+ const gitFiles = async (root: string): Promise<string[] | null> => {
48
+ const inside = await git(root, ['rev-parse', '--is-inside-work-tree']);
49
+ if (inside.code !== 0) {
50
+ if (/not a git repository/i.test(inside.err)) return null;
51
+ throw new Error(`git rev-parse failed in ${root}: ${inside.err}`);
52
+ }
53
+ if (inside.out.trim() !== 'true') return null; // inside a .git dir or a bare repo
54
+ if ((await git(root, ['check-ignore', '-q', '.'])).code === 0) return null;
55
+ const listed = await git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
56
+ if (listed.code !== 0) throw new Error(`git ls-files failed in ${root}: ${listed.err}`);
57
+ // An untracked nested repo or worktree is listed as `dir/`; it isn't a file of this repo.
58
+ // A submodule is a gitlink, not a file, so its contents aren't walked either.
59
+ return [...new Set(listed.out.split('\0'))].filter((p) => p !== '' && !p.endsWith('/'));
60
+ };
61
+
62
+ // A directory that isn't part of a repo (a fixture, an unpacked tarball, a fresh docs folder):
63
+ // every file in it.
64
+ const allFiles = async (root: string): Promise<string[]> => {
65
+ const files: string[] = [];
66
+ for await (const entry of new Glob('**/*').scan({ cwd: root, onlyFiles: true, dot: true }))
67
+ files.push(entry.replaceAll('\\', '/'));
68
+ return files;
69
+ };
70
+
71
+ // A regular file, not a symlink: a link may point outside the repo (stamp would write there) or
72
+ // at another listed file (stamped twice). Deleted-but-indexed files are skipped too.
73
+ const isFile = (root: string, path: string): boolean => {
74
+ try {
75
+ return lstatSync(resolve(root, path)).isFile();
76
+ } catch {
77
+ return false;
78
+ }
79
+ };
80
+
81
+ // Repo-relative files not ignored, sorted for deterministic output. `keep` decides which of the
82
+ // rest atlas considers (an include list, or the default in analyze.ts).
11
83
  export const walkFiles = async (
12
84
  root: string,
13
- include: string[] = DEFAULT_INCLUDE,
14
- ignore: string[] = [],
85
+ ignore: string[],
86
+ keep: (path: string) => boolean,
15
87
  ): Promise<string[]> => {
16
- const glob = new Glob('**/*');
17
- const files: string[] = [];
18
- for await (const entry of glob.scan({ cwd: root, onlyFiles: true, dot: false })) {
19
- const path = entry.replaceAll('\\', '/');
20
- if (matchesAny(ALWAYS_IGNORE, path)) continue;
21
- if (!matchesAny(include, path)) continue;
22
- if (matchesAny(ignore, path)) continue;
23
- files.push(path);
24
- }
25
- return files.sort();
88
+ if (!existsSync(root)) throw new Error(`no such directory: ${root}`);
89
+ const listed = (await gitFiles(root)) ?? (await allFiles(root));
90
+ return listed
91
+ .filter(
92
+ (path) =>
93
+ !matchesAny(ALWAYS_IGNORE, path) &&
94
+ !matchesAny(ignore, path) &&
95
+ keep(path) &&
96
+ isFile(root, path),
97
+ )
98
+ .sort();
26
99
  };
@@ -20,9 +20,12 @@ const cachePathFor = (root: string, cacheDir: string, version: string): string =
20
20
  );
21
21
 
22
22
  // A `.atlas/` edit (new concept, new rule) makes the cached graph wrong before the TTL does.
23
+ // Every file under `.atlas/`, helpers in subfolders included (their imports load too).
23
24
  const configNewerThan = (root: string, mtimeMs: number): boolean => {
24
25
  const dir = join(root, '.atlas');
25
- return readdirSync(dir).some((entry) => statSync(join(dir, entry)).mtimeMs > mtimeMs);
26
+ return readdirSync(dir, { recursive: true }).some(
27
+ (entry) => statSync(join(dir, String(entry))).mtimeMs > mtimeMs,
28
+ );
26
29
  };
27
30
 
28
31
  // The hooks fire on every Read/Grep and a full analyze walks the whole tree (seconds on a
@@ -20,7 +20,7 @@ export const toAdditionalContext = (text: string): string => {
20
20
  if (trimmed === '') return '';
21
21
  const body =
22
22
  trimmed.length > MAX_CHARS
23
- ? `${trimmed.slice(0, MAX_CHARS)}\n… (truncated; bunx atlas query --partOf <concept> lists the rest)`
23
+ ? `${trimmed.slice(0, MAX_CHARS)}\n… (truncated; bunx @inixiative/atlas query --partOf <concept> lists the rest)`
24
24
  : trimmed;
25
25
  return JSON.stringify({
26
26
  suppressOutput: true,
@@ -73,7 +73,7 @@ export const renderNeighbourhood = (
73
73
  siblings.length > SIBLING_SAMPLE ? [` … ${siblings.length - SIBLING_SAMPLE} more`] : [];
74
74
  const consumers = graph.usesConsumers[concept]?.length ?? 0;
75
75
  return [
76
- `${concept} — ${siblings.length} other file(s)${consumers > 0 ? `, ${consumers} consumer(s) via @uses` : ''}; \`bunx atlas query --partOf ${concept}\` lists all`,
76
+ `${concept} — ${siblings.length} other file(s)${consumers > 0 ? `, ${consumers} consumer(s) via @uses` : ''}; \`bunx @inixiative/atlas query --partOf ${concept}\` lists all`,
77
77
  ...sample,
78
78
  ...more,
79
79
  ].join('\n');
@@ -81,7 +81,7 @@ export const renderNeighbourhood = (
81
81
  const usesBlock =
82
82
  membership.uses.length > 0
83
83
  ? [
84
- `@uses ${membership.uses.join(', ')} — load-bearing dependencies; \`bunx atlas query --partOf <concept>\` shows what implements each`,
84
+ `@uses ${membership.uses.join(', ')} — load-bearing dependencies; \`bunx @inixiative/atlas query --partOf <concept>\` shows what implements each`,
85
85
  ]
86
86
  : [];
87
87
  const kinds = kindLines(graph, relPath, membership.partOf, options.kinds ?? REACH_KINDS);
@@ -230,7 +230,7 @@ const conceptBlock = (graph: Graph, concept: string, label: string): string => {
230
230
  const consumers = graph.usesConsumers[concept]?.length ?? 0;
231
231
  const doc = graph.thesaurus[concept]?.doc;
232
232
  return [
233
- `${concept}${label} — ${files.length} file(s)${consumers > 0 ? `, ${consumers} consumer(s) via @uses` : ''}; \`bunx atlas query --partOf ${concept}\` lists all`,
233
+ `${concept}${label} — ${files.length} file(s)${consumers > 0 ? `, ${consumers} consumer(s) via @uses` : ''}; \`bunx @inixiative/atlas query --partOf ${concept}\` lists all`,
234
234
  ...(doc ? [` read: ${doc}`] : []),
235
235
  ...sample,
236
236
  ...more,
package/src/index.ts CHANGED
@@ -4,8 +4,10 @@ export type { Graph } from './commands/graph.ts';
4
4
  export {
5
5
  atlasHookEntry,
6
6
  CLAUDE_SETTINGS,
7
+ type HookRunner,
7
8
  hookCommandFor,
8
9
  mergeAtlasHooks,
10
+ runnerFor,
9
11
  type SetupReport,
10
12
  setupClaudeHooks,
11
13
  } from './commands/setup.ts';
@@ -35,7 +37,13 @@ export {
35
37
  renderConceptMatches,
36
38
  renderNeighbourhood,
37
39
  } from './hook/neighbourhood.ts';
38
- export { type AtlasAnnotation, parseAtlasBlock, type UsesState } from './parse/parseAtlasBlock.ts';
40
+ export {
41
+ type AtlasAnnotation,
42
+ type LocatedBlock,
43
+ locateAtlasBlock,
44
+ parseAtlasBlock,
45
+ type UsesState,
46
+ } from './parse/parseAtlasBlock.ts';
39
47
  export { invert } from './registry/invert.ts';
40
48
  export {
41
49
  type ConceptEntry,
@@ -45,4 +53,16 @@ export {
45
53
  type Thesaurus,
46
54
  type ThesaurusEntry,
47
55
  } from './registry/types.ts';
56
+ export {
57
+ COMMENT_STYLES,
58
+ COMMENT_TABLE,
59
+ type CommentStyle,
60
+ type CommentStyleName,
61
+ type CommentTable,
62
+ entryFor,
63
+ mergeCommentTable,
64
+ preambleEnd,
65
+ styleFor,
66
+ styleNameFor,
67
+ } from './syntax/comments.ts';
48
68
  export { DEFAULT_KINDS, type DefaultKind } from './vocab/kinds.ts';